Text Truncated. Only the first 1MB is shown below. Download the file for the complete contents.
32-Bit QuickDraw: Version 1.2 Features
Imaging M.IM.32BitQD
Written by: Guillermo Ortiz April 1990
This Technical Note describes the changes and enhancements to 32-Bit QuickDraw from version 1.0 (as shipped on the original Color Disk) to version 1.2, which ships with System Software 6.0.5 and later. This Note assumes familiarity with Inside Macintosh, Volume V, Color QuickDraw, and 32-Bit QuickDraw release notes.
32-Bit QuickDraw
Version 1.0 of 32-Bit QuickDraw shipped in May 1989 in response to the growing need for Color QuickDraw support for direct color devices and pictures (PICT2) and video boards for large-screen monitors which require 32-bit addressing for black and white operation. This original version of 32-Bit QuickDraw was a separate file that had to be copied manually into the System Folder. With the introduction of the Macintosh IIci, Apple put 32-Bit QuickDraw into ROM. Now System Software 6.0.5 and later offer 32-Bit QuickDraw as an integral part of the System Software which can be installed by the standard Installer (although the file is still separate).
This Note describes the changes and enhancements in version 1.2 of 32-Bit QuickDraw from version 1.0. Beginning with version 1.2, QuickDraw functionality is identical on all Color QuickDraw machines, including all the performance improvements which were originally only available in the IIci ROM.
New Features (In No Particular Order)
PICTs Contain Font Name Information
Every time you draw text inside of an _OpenPicture and _ClosePicture pair, QuickDraw stores the name of the current font and uses it when playing back the picture. The opcode used to save this information is $002C and its data is as follows:
PictFontInfo = Record
length : Integer; { length of data in bytes }
fontID : Integer; { ID in the source system }
fontName : Str255;
END;
QuickDraw only saves this information one time for each font used in a picture. When QuickDraw plays back a picture, it uses the fontID as a reference into the list of font names which are used to set the correct font on the target system.
For example, the following code:
GetFNum('Venice', theFontID); { Set a font before opening PICT}
TextFont(theFontID);
pHand2 := OpenPicture (pictRect);
MoveTo(20,20);
DrawString(' Better be Venice');
GetFNum('Geneva', theFontID);
TextFont(theFontID);
MoveTo(20,40);
DrawString('Geneva');
GetFNum('New York', theFontID);
TextFont(theFontID);
MoveTo(20,60);
DrawString('New York');
GetFNum('Geneva', theFontID);
TextFont(theFontID);
MoveTo(20,80);
DrawString('Geneva');
ClosePicture;
generates a picture containing font information like this:
OpCode 0x002C {9,
"0005 0656 656E 6963 65"} /* save current font */
TxFont 'venice'
DHDVText {20, 20, " Better be Venice"}
OpCode 0x002C {9, /* save next font name */
"0003 0647 656E 6576 61"}
TxFont 'geneva'
DVText {20, "Geneva"}
OpCode 0x002C {11, /* ditto */
"0002 084E 6577 2059 6F72 6B"}
TxFont 'newYork'
DVText {20, "New York"}
TxFont 'geneva' /* second Geneva does not
need another $002C guy */
DVText {20, "Geneva"}
This feature works regardless of the type of picture being saved, including old style PICTs in a black and white port. Using _OpenCPicture instead of _OpenPicture to start a recording session results in the same functionality.
Direct PixPat Structures Now Supported
QuickDraw now supports 16-bit and 32-bit per pixel PixPat structures (patType = 1). In addition, it now supports a new patType (3) which uses dithering whenever 16-bit or 32-bit pixel patterns are displayed on indexed devices.
Direct 'cicn' Resources Now Supported
QuickDraw now supports 16-bit and 32-bit per pixel 'cicn' resources. The 16-bit per pixel is particularly cool since you save the space required for an 8-bit 'clut'.
GWorlds Can Now Be Allocated in MultiFinder Temporary Memory
You can now use the new useMFTempBit (bit 2) in a call to NewGWorld as an option to allocate pixels in MultiFinder temporary memory. In addition, you can now allocate screen buffers in MultiFinder temporary memory using the following routine, defined in Pascal and C:
FUNCTION NewTempScreenBuffer (globalRect: Rect; purgeable: BOOLEAN;
_CopyBits now supports the ditherCopy transfer mode whenever the destination device is between one and eight bits per pixel, regardless of the depth of the source image. With this support, an eight-bit image can now be approximated on a one-bit or a four-bit device by using error diffusion. Furthermore, an eight-bit image could also be dithered to a different set of 256 colors or a four-bit image could be dithered to an eight-bit device that does not have the desired colors.
32-Bit Addressed PixMap Structures
Version 1.2 defines a new pmVersion (baseAddr32 = 4) for 32-bit pointer baseAddr values. The baseAddr of such PixMap structures is treated as a 32-bit address, so no stripping or address translation is performed on it in 32-bit mode. This is a specially useful feature when the base address of a PixMap points to a NuBus™ address, for example in a video grabber board.
A new call, Pixmap32Bit, is now available to inquire if a given PixMap requires 32-bit addressing.
Version 1.2 updates GetPixBaseAddress to return the address of any PixMap. The routine does the right address translation or stripping for all PixMap structures, including screen devices, unlocked GWorlds, and 32-bit addressed PixMap structures. The address it returns is only valid in 32-bit addressing mode. Also unless the PixMap is locked and made unpurgeable, the address returned by GetPixBaseAddress is only valid until any call to QuickDraw or the toolbox is made.
_CopyBits from Screen Devices
The picture recording mechanism has changed so that if you call _CopyBits while recording a picture with the source PixMap being a screen device, the data is correctly accumulated into the picture. Note that if the screen being copied is not the main screen, then the PixMap must be a 32-bit addressed PixMap. No auxiliary screen buffer is allocated if the source rectangle covers only one screen.
New Picture Recording Trap
Version 1.2 adds a new call, _OpenCPicture, to create pictures that contain information regarding the native resolution of the recorded image. When QuickDraw draws this picture, it scales the image to the resolution of the target device. Applications that need to scale the images directly can also access this information.
FUNCTION OpenCPicture(VAR CPictInfo:CPictRecord):PicHandle;
For information on bug fixes in the System Software 6.0.5 release of 32-Bit QuickDraw (version 1.2), please refer to the System Software 6.0.5 Change History, which is available on the Developer CD Series, AppleLink in the Developer Services Bulletin Board (Developer Services: Macintosh Developer Technical Support: System Software), and the Apple FTP site on the Internet in the ~ftp/pub/dts/sw.license.
Note that the dispatching mechanism for the new _QDOffscreen calls is slightly different than previously documented; it now requires that the high word passed in D0 contain the total length of the parameters (in bytes). The reason for this change is that if the call is made in an earlier version of 32-Bit QuickDraw, the system can strip the parameters from the stack and return QDError set to the caller (instead of crashing).
Further Reference:
• Inside Macintosh, Volume V, Color QuickDraw
• 32-Bit QuickDraw Release Notes (available from APDA)
• System Software 6.0.5 Change History
• d e v e l o p, Issue I
NuBus is a trademark of Texas Instruments.
Basic QuickDraw Q&As
Imaging M.IM.BasicQD.Q&As
Revised by: Developer Support Center October 1992
Written by: Developer Support Center October 1990
This Technical Note contains a collection of Q&As relating to a specific topic—questions you’ve sent the Developer Support Center (DSC) along with answers from the DSC engineers. While DSC engineers have checked the Q&A content for accuracy, the Q&A Technical Notes don’t have the editing and organization of other Technical Notes. The Q&A function is to get new technical information and updates to you quickly, saving the polish for when the information migrates into reference manuals.
Q&As are now included with Technical Notes to make access to technical updates easier for you. If you have comments or suggestions about Q&A content or distribution, please let us know by sending an AppleLink to DEVFEEDBACK. Apple Partners may send technical questions about Q&A content to DEVSUPPORT for resolution.
New Q&As and Q&As revised this month are marked with a bar in the side margin.
Sending PostScript via PostScriptHandle PicComment
Written: 5/1/90
Last reviewed: 10/9/91
If I use the PostScriptHandle PicComment to send PostScript code to the LaserWriter driver, do I need to open a picture and then draw the picture to the driver, or can I just use the PicComment with no picture open while drawing to the printer’s grafPort?
___
You don’t need to create a picture with your PicComment in it and draw the picture to the driver. The best method for sending PostScript code to the LaserWriter is to use the PostScriptHandle PicComment documented in the Macintosh Technical Note #91, “Optimizing for the LaserWriter—Picture Comments,” as shown below.
PrOpenPage(...)
{ Send some QuickDraw so that the Printing Manager gets a }
The above code prints a line on any type of printer, PostScript or not. The first MoveTo/LineTo combination is required to give the LaserWriter driver a chance to define a clipping region. The LaserWriter driver replaces the grafProcs record in the grafPort returned from PrOpenDoc. In order for the LaserWriter driver to get execution time, you must execute a QuickDraw drawing routine that calls one of the grafProcs. In this case, the MoveTo/LineTo combination calls the StdLine grafProc. When StdLine executes, it notices that the grafPort has been reinitialized, and therefore initializes the clipping region for the port. Until the MoveTo/LineTo combination is executed, the clipping region for the port is set to (0,0,0,0). If PostScript code is sent via the PostScriptHandle PicComment before executing any QuickDraw routines, all PostScript operations will be clipped to (0,0,0,0).
The next thing that’s done is to send the PostScriptBegin PicComment. This comment is recognized only by PostScript printer drivers. When the driver receives this comment, it saves the current state of the PostScript device (by executing the PostScript gsave operator), then disables all QuickDraw drawing operations. This way, the QuickDraw representation of the graphic will be ignored by PostScript devices. In the above example, the second MoveTo/LineTo combination is executed only on non-PostScript devices.
The next PicComment is PostScriptHandle, which tells the driver that the data in thePSHandle is to be sent to the device as PostScript code. The driver then passes this code unchanged to the PostScript device for execution. The PostScriptHandle comment is recognized only by PostScript printer drivers.
The last PicComment, PostScriptEnd, tells the driver to restore the previous state of the device (via a PostScript grestore call), and to enable QuickDraw drawing operations.
Since most PicComments are ignored by QuickDraw devices, only the QuickDraw representation is printed. Since PostScriptBegin tells PostScript drivers to ignore QuickDraw operations, only the PostScript representation is printed on PostScript devices. This is a truly device-independent method for providing both PostScript and QuickDraw representations of a document.
Macintosh PICT-to-PostScript conversion
Written: 8/3/90
Last reviewed: 10/8/91
How do I convert PICT format data to PostScript in my printer driver?
___
Converting PICT files to PostScript involves a detailed understanding of both bitmaps (or pixmaps) and the graphics state in PostScript, which is a data structure defining the context in which other graphic operators in PostScript execute. If you don’t know PostScript, the following manuals are a must:
• PostScript Language Tutorial and Cookbook (Addison-Wesley) is an introduction to PostScript. • PostScript Language Reference Manual (Addison-Wesley).
• PostScript Language Program Design (Addison-Wesley) details designing efficient PostScript programs. It has a lot of useful sample programs on topics like writing a print spooler.
You need to convert all the QuickDraw operations in a PICT to corresponding PostScript operations. To get a feel for this conversion, you can analyze the PostScript dump from a LaserWriter to see how it converts a PICT to PostScript. Under System 6.x, a PostScript dump can be obtained by pressing Command-K while printing. Under System 7.0, you can get a dump by selecting the PostScript File option in the Print dialog.
Some areas of QuickDraw, such as transfer modes, do not have a correspondence in PostScript. The PostScript imaging model is designed so that all areas of a page affected by an image are marked as if with opaque paint. Using image masks can help. See the Graphics chapter in the PostScript reference manual.
PICT-to-PostScript conversion can be a long process, especially if one is unfamiliar with PostScript. Using the above books and the PostScript dump from the LaserWriter (but ONLY as a general guide) should help.
Calling InitCursor instead of SetCursor
Written: 10/23/90
Last reviewed: 2/20/91
Is it legal to call InitCursor instead of SetCursor(arrow) when I want to set the cursor to an arrow (after my normal one-time program initialization code, in my UpdateCursor routine)? The only reason I'd want to do such a skanky thing is to save code. Calling a trap with no parameters is less code than one with parameters. What, exactly, if anything, does InitCursor do besides setting the cursor to an arrow and setting the cursor level to zero?
___
There's no problem at all with this, as long as you are aware that the hidden, busy, and obscured states are cleared when you call InitCursor, so if the cursor was hidden or obscured for good reason it'll suddenly reappear. It also gets the arrow from QuickDraw, of course, but that's not a problem.
PICT fontName opcode
Written: 10/31/90
Last reviewed: 2/20/91
Is there an up-to-date canonical source for PICT opcodes? In “Night of the Living Disc,” as far as I can see, the only list of PICT opcodes is in the Macintosh Tech Note “QuickDraw’s Internal Picture Definition” which does not mention opcode $2C. It appears that opcode $2C concerns font names. I recall seeing a patch for PictDetective named "fontnameop" or something like that. However I can't be sure that $2C is the only new opcode.
___
The fontName opcode is documented in the Technical Note “32-Bit QuickDraw: Version 1.2 Features.” Note also that since the introduction of 32-Bit QuickDraw there are two more bitmap opcodes for direct RGB PixMaps $009A (DirectBitsRect) and $009B (DirectBitsRgn). The QuickDraw section of Inside Macintosh Volume VI has all these opcodes listed in a single place, making it easier to get the necessary info. Here is the info on font names and pictures from the "32-Bit QuickDraw..." Tech Note:
PICTs Contain Font Name Information
Every time you draw text inside of an _OpenPicture and _ClosePicture pair,
QuickDraw stores the name of the current font and uses it when playing back
the picture. The opcode used to save this information is $002C and its data is
as follows:
PictFontInfo = Record
length : Integer; { length of data in bytes }
fontID : Integer; { ID in the source system }
fontName : Str255;
END;
QuickDraw saves this information only one time for each font used in a picture. When QuickDraw plays back a picture, it uses the fontID as a reference into the list of font names which are used to set the correct font on the target system.
For example, the following code:
GetFNum('Venice', theFontID); { Set a font before opening PICT}
TextFont(theFontID);
pHand2 := OpenPicture (pictRect);
MoveTo(20,20);
DrawString(' Better be Venice');
GetFNum('Geneva', theFontID);
TextFont(theFontID);
MoveTo(20,40);
DrawString('Geneva');
GetFNum('New York', theFontID);
TextFont(theFontID);
MoveTo(20,60);
DrawString('New York');
GetFNum('Geneva', theFontID);
TextFont(theFontID);
MoveTo(20,80);
DrawString('Geneva');
ClosePicture;
generates a picture containing font information like this:
OpCode 0x002C {9,
"0005 0656 656E 6963 65"} /* save current font */
TxFont 'venice'
DHDVText {20, 20, " Better be Venice"}
OpCode 0x002C {9, /* save next font name */
"0003 0647 656E 6576 61"}
TxFont 'geneva'
DVText {20, "Geneva"}
OpCode 0x002C {11, /* ditto */
"0002 084E 6577 2059 6F72 6B"}
TxFont 'newYork'
DVText {20, "New York"}
TxFont 'geneva' /* second Geneva does not
need another $002C guy */
DVText {20, "Geneva"}
This feature works regardless of the type of picture being saved, including old style PICTs in a black-and-white port. Using _OpenCPicture instead of _OpenPicture to start a recording session results in the same functionality.
X-Refs:
Inside Macintosh Volume VI
Macintosh Technical Note “QuickDraw's Internal Picture Definition”
Macintosh Technical Note “32-Bit QuickDraw: Version 1.2 Features”
Using PicComments to rotate text
Written: 11/28/90
Last reviewed: 12/19/90
I have a PostScript routine (using TextBegin/TextEnd) to generate bitmapped rotated text on the screen (which can be later printed on QuickDraw printers). Why do I get duplicate text? I get both bitmapped rotated text and PostScript rotated text when I print on the LaserWriter II, and both bitmapped rotated text and horizontal text on the ImageWriter. When I make a machine dependent check (check type of printer) and call the proper printing procedure, it works fine. Because of the speed and memory considerations of generating the rotated bitmapped text (especially at 300 dpi), is there a way to ensure that the printer will use the PostScript BEFORE generating the bitmap?
___
We will use the following Macintosh PicComments to hide your QuickDraw calls from the LaserWriter, but the ImageWriter will use them:
PostScriptBegin
>> Put your CopyBits and QuickDraw calls to image your rotated
>> bitmapped text here....
PostScriptEnd
By wrapping your QuickDraw code within the PostScriptBegin and PostScriptEnd PicComments, the code will be ignored by the LaserWriter, but the ImageWriter will use the QuickDraw calls. Basically, the PostScriptBegin and PostScriptEnd PicComments tell the LaserWriter driver to turn “off” QuickDraw. In the ImageWriter case, the ImageWriter does not understand the PicComments. Therefore, it will use the QuickDraw calls to create and image your bitmapped text.
Now, we need to use the rotation PicComments to rotate the text on the LaserWriter, but have the ImageWriter ignore the code:
Rect zeroRect;
SetRect (&zeroRect, 0, 0, 0, 0);
TextBegin
TextCenter
ClipRect (&zeroRect);
>> Draw your text to be rotated on the LaserWriter....
ClipRect (&rPageRect);
TextEnd
Wrapping your text drawing call(s) between the ClipRect calls will ensure that the text is drawn only on the LaserWriter. Setting the ClipRect to zero tells the ImageWriter to ignore all QuickDraw calls until the ClipRect is reset to something “real” (actually, a zero ClipRect prevents QuickDraw from drawing anything). After we have completed drawing the rotated text, we reset the ClipRect to the dimensions of rPage (that is, rPage is the image-able area of the currently selected printer—see Inside Macintosh, Volume II, page 150). This will allow all of your normal drawing to continue on the ImageWriter and LaserWriter. If you did not reset the ClipRect after the TextEnd call, nothing would be drawn on the ImageWriter or LaserWriter.
Using dithered drawing mode with QuickDraw
Written: 11/28/90
Last reviewed: 12/19/90
When I draw a 32-bit Macintosh PICT image from a file to an 8-bit port via an offscreen GWorld, I use dither mode in the CopyBits call and the results are quite impressive. If there is not enough memory to allocate the GWorld, I draw the image directly to the port. But since there does not seem to be any way to tell QuickDraw to use dithered drawing mode, the image looks horrible.
Do you have any suggestions? I have installed bottleneck procs to allow DrawPicture to get its data from the file instead of the handle in memory. Is there a way, while in the bottlenecks, to find the CopyBits call that comes from the picture and force it to use dithered mode instead of source mode? I don’t want to try and parse the PICT myself, but I thought that maybe a QuickDraw global could be modified in my StdBits proc to force dithered drawing for that operation only?
___
You can install a StdBits or bitsProc bottleneck procedure to get all the CopyBits calls when the picture is being played back. One of the parameters to the StdBits call is the mode. You can install a procedure that saves the current mode, and then passes ditherMode to the original StdBits proc. This is all you should need to do. It’s been done here so we know it works, only not in any form that can be sent to you as sample code at this time.
Code for reversing Macintosh PICT images
Written: 3/4/91
Last reviewed: 8/30/91
Is there a simple way to put PICT images up in mirror image format, or is there sample code showing how to flip an offscreen bitmap?
___
There is no easy way to do this, nor do we have sample code showing how to flip an offscreen bitmap. Indeed, the best way to do what you want is to draw it to an offscreen pixel map and reverse it.
If you are using Color QuickDraw, always draw it to an 8-bit-per-pixel offscreen bitmap, and then the reverse is a very simple task. Here is some sample Pascal code that might roughly do what you want, with the following assumptions:
1. You are going to add error checking where appropriate.
2. Rowbytes correspond exactly to pixel width of the port.
{ The scan line is simply an array [0..RowBytes] of Byte, and since this is }
{ 8 bits per pixel, each one is a single pixel.}
Size:=thePixMap^.RowBytes;
For Index:=0 to (Size div 2) do
begin
tempPixel:=ThisScanLine^[Index];
ThisScanLine^[Index]:=ThisScanLine[Size-Index-1];
ThisScanLine^[Index]:=tempPixel;
end;
end;
This same procedure can be used also to swap a 1-, 2- or 4-bit-per-pixel pixmap if you add a function that accepts a byte and swaps the pixels in it.
Use srcOr instead of srcCopy for Macintosh text drawing
Written: 6/4/91
Last reviewed: 10/9/91
DrawText with srcCopy takes six times as long as with srcOr now that my Macintosh is running System 7. Why is this so slow? Is this a bug in System 7?
___
It’s true that srcCopy is slower than srcOr when handling text, especially in color mode. This loss in speed occurs because CopyBits is a lot smarter than it used to be. It can handle foreground and background colors a lot better, but that improvement came at the cost of speed. Our recommended method for drawing text is to erase before drawing, and use srcOr to draw, not srcCopy. Alternatively, you could draw colorized text in srcOr mode off screen and then use CopyBits to draw it on the screen in srcCopy mode without colorization.
Techniques for graying Macintosh text
Written: 6/3/91
Last reviewed: 8/1/91
How do I draw grayed-out text on the Macintosh, like the text for disabled buttons or menu items?
___
There are currently two different kinds of grayed text: First, there’s
“patterned” gray, where every other dot is missing. This really only looks good with Chicago or other heavy fonts and was always used for graying out menus and controls in system software through 6.0.x, and is still used in 7.0 when the screen is set to less than 4 bits deep. This is done by first drawing the text in a normal, srcCopy transfer mode. Then a gray rectangle is drawn over the text using the patBic mode. This “erases” half the bits in the text, and is rapid enough that there is very rarely any flicker.
The second kind of text is the actually gray text, which is used in System 7 on screens that are 4 bits deep or deeper for menus, controls, and other grayed text. To draw this text, just call GetGray (as documented on page 17-27 of Inside Macintosh, Volume VI) to get an appropriate gray. Then draw the text in that color.
Updating Macintosh cursor without mouse competition
Written: 6/12/91
Last reviewed: 8/1/91
How can I programmatically move the Macintosh mouse without the real mouse interfering?
___
The real answer to your question is twofold: First, you can do exactly what you want to do with the sample included below. HOWEVER, this is not a good thing to do, it would be better if you took the solution used in Apple’s Guided Tour disks: Always hide the cursor and then decouple the cursor from the mouse. Then, instead of using the system’s cursor, simply draw your own “cursor” using QuickDraw and treat it as a little animated bitmap on the screen. This avoids all the problems that you have with the mouse competing. (Apple does update the mouse globals with the mouse position so that other things function correctly.)
Now, as promised, here is the way to do what you want using the real cursor. As you have discovered, setting the crsrCouple variable to false prohibits the mouse from affecting the cursor; unfortunately, it also prohibits the jcrsrTask routine from drawing the cursor. The solution to this is to set crsr couple to true, call the cursor drawing routine jCrsrTask yourself, and then set the crsrCouple variable to false, as shown below:
procedure callcrsr;
inline $2078 ,$08EE ,$4E90;
{ move.L jcrsrTask,A0
jsr (A0) }
Procedure FudgeMouse;
type PointPtr=^Point;
var RawMouse:PointPtr;
MTemp:PointPtr;
RandPt:Point;
CrsrNew:ptr;
CrsrCouple:ptr;
fred:Longint;
begin
RawMouse:=PointPtr($82C);
MTemp:=PointPtr($828);
CrsrNew:=ptr($8CE);
CrsrCouple:=ptr($8CF);
RandPt:=RawMouse^;
repeat
RandPt.h:=RandPt.h+1;
RandPt.V:=RandPt.v+1;
RawMouse^:=RandPt;
MTemp^:=RandPt;
CrsrNew^:=1;
CrsrCouple^:=1;
callCrsr;
crsrCouple^:=0;
repeat until fred<tickCount;
fred:=tickCount+3;
until Button;
crsrCouple^:=1;
end;
System 7 QuickDraw DrawText performance
Written: 11/4/91
Last reviewed: 11/27/91
We’ve noticed that using DrawText is much slower in System 7, especially when drawing in color (anything other than black on white). What can be done to restore the drawing speed to System 6 levels?
___
A QuickDraw function like DrawString or DrawText will be slower under certain circumstances in System 7 than System 6. Specifically, if you are drawing in srcCopy mode and you colorize the text—that is, foreground color is not black and background color is not white (Inside Macintosh Volume VI, page 17-16)—then QuickDraw really slows down as you have noticed. SOMETIMES, the speed of drawing is 6 times as slow as System 6.
The cause of this slowness is a known System 7 bug. The bug has concerned the engineers greatly and will be responded to in an appropriate manner in the future.
There are a few workarounds: One, you can avoid using the srcCopy mode and use the default srcOr mode instead. However, this is not a real workaround, since you may have essential reasons to use srcCopy. The other option is to create an offscreen pixmap or GWorld and perform a DrawText with srcOr to this GWorld with colorization. Then, you can perform a CopyBits from the offscreen to the screen with srcCopy mode and no colorization. Using CopyBits will not cost you much time. Again, this is a workaround and is not ideal.
The srcOr is a bit slower than in System 6.0.x, but it does not have a bug; rather it is a side effect of system enhancements. The slow speed is a trade-off taken to receive the host of other benefits.
Macintosh animation samples
Written: 11/6/91
Last reviewed: 11/6/91
Do you have an example of flicker-free animation on the Macintosh?
___
We have some good stuff that’s written in MPW Pascal. It’s DTS Sample Code #16, OffSample, and this uses some routines defined in DTS Sample Code #15, OffScreen. Also, the System 7.0 CD sample code folder contains a smaller sample called “GMonde” that uses GWorlds.
CopyBits bug and workaround
Written: 6/26/91
Last reviewed: 8/13/91
Has anyone run across what I’m told is a bug in CopyBits? It works like this: In the deep, dark workings of CopyBits, some routine tries to read the two bytes preceding the baseAddress of the source PixMap. If the baseAddress is at the start of a card’s NuBus space and there isn’t a card filling the adjacent space, this causes a bus error! Has anyone found a good workaround?
___
The short answer is: you’re right. QuickDraw inadvertently reads from memory below the base address of a pixmap. The workaround is to place the video base address 32 bytes into the RAM on the card; if the card you’re using doesn’t have this workaround, there’s nothing you can do other than making sure there’s a card in the next-lower slot.
Macintosh picture (PICT) 90-degree rotation
Written: 7/23/91
Last reviewed: 8/30/91
The trick for rotating a Macintosh QuickDraw picture 90 degrees is to intercept all bottlenecks and exchange the x and y coordinates. Then, call OpenPicture to receive the rotated picture, call DrawPicture(unrotatedPicture), and then call ClosePicture on the rotated picture. You’re done! QuickDraw spins out the DrawPicture call into its component parts, but runs each component through the bottlenecks first, so they get rotated (by YOUR bottleneck intercepts) and stuck into the new picture, already rotated.
Here‘s a bottleneck intercept for StdLine that rotates a PICT composed entirely of Line commands (which depend on the current pen position):
procedure MyLineProc(newPt: point);
var
tempV : integer;
begin
tempV := thePort^.pnLoc.v; { Swap current pen location coordinates }
tempV := thePort^.pnLoc.v; { Restore current pen location coordinates }
thePort^.pnLoc.v := thePort^.pnLoc.h;
thePort^.pnLoc.h := tempV;
end;
Notice that the start coordinates as well as the destination coordinates must be swapped before calling StdLine. The resulting pen location is swapped back again after the operation, so the port looks like it should if unrotated drawing were performed. For things that don’t depend on the current pen location, things are simplified a little bit.
You’ll still need bitmap rotation code for the StdBits and StdText intercepts.You might do StdText by setting the port to an offscreen one you create earlier, calling QuickDraw’s StdText, and then calling your bitmap rotation code to copy it into the destination.
Macintosh QuickDraw and pen characteristic routines
Written: 8/12/91
Last reviewed: 11/6/91
When generating pictures and then looking at the corresponding Macintosh PICT file, we notice that QuickDraw is optimizing PnMode, PnPat, and PnSize. Can you tell us how to stop QuickDraw from optimizing, and how to know when QuickDraw will optimize?
___
QuickDraw does not optimize away new pen characteristic routines, but it does insert them into pictures just before a drawing routine that uses the pen rather than place them where they are called. Therefore, you may not see your new pen characteristic routine until later in a picture when it is about to be used. Opcodes for pen characteristics are inserted into the picture when they are changed from the previous time they’re used.
Detecting whether application window is partially hidden
Written: 9/26/92
Last reviewed: 1/27/92
We draw directly to the screen to gain the fastest possible animation speed, and when we need compatibility—such as when windows overlap or for multiple screens—we do use CopyBits. How do we tell whether the window is hidden or that the visible part is not rectangular?
___
If your window is covered partially by another applications window or if your layer has been hidden by the process menu, the visRgn of your window’s grafport will not be the portRect anymore. (Keep in mind that if you scroll by modifying the portRect of the grafport, then you’ll have to do a more complex calculation...) Here is a small Pascal routine that returns this information:
Function UseCopyBits(thePort:grafptr):Boolean;
begin
UseCopyBits:= NOT( (thePort^.VisRgn^^.rgnSize=10) and
(thePort^.visRgn^^.RgnBBox=thePort^.PortRect) );
end;
The rect strucRgn^^.rgnBBox will be zero for a visible window if the system
has hidden the application.
How to tell whether GetPictInfo is available
Written: 12/16/91
Last reviewed: 2/24/92
How do you determine whether the function GetPictInfo is available? Gestalt doesn’t seem to have the right stuff?!
___
To determine whether the GetPictInfo routine is available, check the system version number with the Gestalt function. The GetPictInfo routine is available under system software version 7.0 and later. Use the Gestalt selector gestaltSystemVersion to determine the version of the system currently running. In most cases you shouldn’t rely on the system version to determine if features are available. However, in this case, this is the only way to determine if the Picture Utilities Package is available.
See Inside Macintosh Volume VI page 3-42 for information on using Gestalt to check the System version number. See Inside Macintosh Volume VI page 18-3 for information on the Picture Utilities Package.
For example, the following C function will determine if the GetPictInfo call is available:
#include <GestaltEQU.h>
Boolean IsGetPictInfoAvail()
{
OSErr err;
long feature;
err = Gestalt(gestaltSystemVersion,&feature);
/*-- check for system 7 and above --*/
return (feature >= 0x00000700);
}
or, if you prefer Pascal:
function IsGetPictInfoAvail: Boolean;
var
err: OSErr;
feature: longint;
begin
err := Gestalt(gestaltSystemVersion, feature);
(*-- check for system 7 and above --*)
IsGetPictInfoAvail := (feature >= $00000700);
end;
GrafPort patStretch: valid values
Written: 12/19/91
Last reviewed: 2/6/92
I’d like to know more about that PatStretch field inside a GrafPort or CGrafPort. If I stuff a values in PatStretch(4) then nothing happens; prints look the same, even using a standard bottleneck. Please tell me how I can get this to work.
___
PatStretch only works with values of 2 or 3. With any other value, it defaults to no stretching. The “2” case was created because of the ImageWriter (72->144 dpi) situation. The “3” case was added to support the ImageWriter LQ and the AppleFax modem.
So why wasn’t a “4” (72->300 dpi) handler added for the LaserWriter driver? Good question. Somehow or other it was decided that pattern stretching for the LaserWriter driver would be done completely by the driver itself. The LaserWriter driver actually does pattern stretching by using a pattern 4 times as large, rather than 4.17. In other words, it really scales the 72 dpi pattern to 288 dpi rather than 300 dpi. You may want to take a similar approach, since you’d only have to work with whole numbers this way.
So, if you want to do 4-times pattern stretching, you must scale the pattern yourself. If you copy the original pattern into an area that’s twice as wide and twice as tall and use that, you should be all set. You’ll need to use PrGeneral to set the printer to the appropriate resolution and Copybits to copy the pattern into the object that needs to be filled, using the “cookie cutter” approach to fill the object.
X-Ref:
Inside Macintosh Volume I, page I-150
Where CopyBits looks for memory to use
Written: 1/3/92
Last reviewed: 1/27/92
Where does CopyBits look for the memory it needs?
___
CopyBits checks the stack to determine if there is enough stack space for it to copy the whole image, which in some cases may be roughly up to 5 extra rowbytes of special effects per row, depending on what special effects such as dithering or scaling are being used. If there is not enough stack space for the whole image, CopyBits then tries for half the image, and keeps halving until it gets down to one row of the image (plus the room for the special effects rows). If there is not enough stack space for one row of the image, then CopyBits tries to allocate temporary memory.
Before allocating temporary memory, CopyBits checks if the temporary memory traps are available. (They are available under both System 6 MultiFinder and System 7.) If the traps are available, CopyBits tries to allocate a 256K byte buffer for use as a “fake” stack. (CopyBits used to try for a 64K block, but this has been changed, and it may change again.) If this succeeds, then all is well and the image is copied. If the temporary memory traps do not exist, or if CopyBits cannot allocate a 256K buffer, then the image is not copied and CopyBits returns.
CopyBits does not check in the application heap for free memory, at least not for its work buffer. For its work buffer it will only use the stack, and after that it resorts to temporary memory, if available. There are some circumstances that may cause memory allocations in the application heap, but this memory is not used for CopyBits’s image buffer.
Also, please note that the implementation of CopyBits is subject to change in future versions of QuickDraw.
PICTs with PostScript PICT comments and memory use
Written: 1/10/92
Last reviewed: 2/17/92
Why does my PICT (including dotted lines) use so much memory when drawn in MacDraw, and even more when drawn in SuperPaint? Do they include PicComments for PostScript?
___
Your guess that it has to do with PicComments is quite right; both MacDraw and SuperPaint include a PostScript representation of the dotted (dashed) lines and some other graphic operations in the PICT, together with the QuickDraw commands. During printing, this allows the LaserWriter driver to take advantage of specific PostScript capabilities that are unavailable in QuickDraw, like primitives for dashed lines.
On the other hand, the PostScript representation for dashed lines is much shorter than the QuickDraw representation, which requires a (long, very long …) sequence of “ShortLine” opcodes. So, another piece of explanation for the large PICT size basically is that QuickDraw does not have facilities to describe dotted lines in an economic way.
SuperPaint also includes a copy of a proprietary dictionary, which adds substantially to the size of a PICT. On the other hand, the code that resides in that dictionary makes the picture’s PostScript representation that much better. Ultimately, WYSIWYG is the goal, and sometimes it takes a little extra code to make that happen. (Incidentally, the PostScript dictionary contained in pictures created by older versions of SuperPaint makes assumptions about the contents of the LaserPrep file which are not true for the recent versions of the LaserWriter driver. Documents containing such pictures will not print correctly any more.)
To determine the primitives that define other nonstandard QuickDraw objects found in drawing applications, you can use MPW’s DeRez function or a third-party utility such as Palomar Software’s PICT Detective on the resource PICT. These tools will provide the opcodes that define the PICT.
Inside Macintosh Vol. V PICT opcode size should be fixed
Written: 1/22/92
Last reviewed: 2/28/92
The definition of PICT version 2 on pages 92-105 of Inside Macintosh Volume V says that the data size of the opcodes $001A and $001B is variable, but also that the data is an RGBColor. This is confusing, since the size of an RGBColor is fixed at six bytes. How can these two opcodes vary in the amount of associated data?
___
Seems like you’ve run into a cut/paste problem. All the opcodes that refer to table 4 are new for Color QuickDraw. Also, most of them are variable in length, so the author simply had a standard notation for anything that was explained further in table 4 (page V-103). The information contained in table 4 is, in fact, accurate. The size information of several of the opcodes listed is not variable even though the preceding pages told you they were.
All you gotta do is believe table 4 and you will be fine.
Code for filling an area fully bounded by polygon
Written: 2/21/92
Last reviewed: 6/11/92
Currently, when a polygon is filled, an even-odd rule is applied to determine which areas of the polygon are to be filled. For our application, we also need to fill all the areas of the defined polygon. Is there a relatively easy way to accomplish this?
___
There are many different ways to fill polygons, as you may know. If you do not want to use QuickDraw’s standard FillPoly routine, you’ll have to create your own. The following sample illustrates one technique that might be used to fill the area fully bounded by a polygon. It can be dropped right into the traffic light sample (sample.p) that ships with MPW as a replacement for its DrawWindow procedure. The green star is drawn using FillPoly and the black star is drawn using my filling technique that uses an offscreen bitmap and calcMask to fill in the poly the desired way, then CopyBits to transfer it to the onscreen port. The drawbacks of this method are that it is not as fast as writing a specialized poly routine; the benefits are that it’s small, fast enough for most operations, and can be used for more than just polygons.
{$S Main}
PROCEDURE DrawWindow(window: WindowPtr);
var MyPoly:PolyHandle;
MyRgn :RgnHandle;
OffPort,OnPort:GrafPtr;
Function CreateOffport(VAR newOffscreen:grafPtr;
inBounds:Rect):Boolean;
var SavePort,NewPort:Grafptr;
begin
GetPort(SavePort);
NewPort:=GrafPtr(NewPtr(sizeof(grafport)));
If MemError<>noErr then Begin
CreateOffport:=false;
EXIT(CreateOffport);
END;
OpenPort(newPort);
With newPort^ do begin
portRect :=Inbounds;
RectRgn(ClipRgn,inBounds);
RectRgn(visRgn, inBounds);
End;
With newPort^.PortBits DO BEGIN
Bounds:=Inbounds;
rowBytes:= ((inBounds.right-inBounds.Left+15) DIV 16) *2;
baseAddr:= NewPtr(rowBytes
* LONGINT(inBounds.Bottom-inBounds.Top));
End;
If MemError <>noErr THEN BEGIN
SetPort(SavePort);
ClosePort(newPort);
DisposPtr(ptr(newPort));
CreateOffport:=false;
END
ELSE BEGIN
EraseRect(inBounds);
newOffscreen :=newPort;
setPort(SavePort);
CreateOffPort:=true;
end;
end;
Procedure KillOffPort(oldOffscreen :GrafPtr);
Begin
ClosePort(oldOffscreen);
DisposPtr(OldOffscreen^.portBits.baseAddr);
DisposPtr(ptr(OldOffScreen));
End;
BEGIN
If NOT (CreateOffPort(offPort,window^.portRect)) THEN Exit(DrawWindow);
If NOT (CreateOffPort(onPort,window^.portRect)) THEN Exit(DrawWindow);
Use crsrNew flag to unobscure cursor without mouse move
Written: 3/3/92
Last reviewed: 6/11/92
The Macintosh QuickDraw routine ObscureCursor hides the cursor until the next time the mouse is moved but isn’t affected by HideCursor or ShowCursor. Our application needs to use ObscureCursor while the user is typing but needs the cursor to be visible after no typing has occurred for a short period. How do we “undo” ObscureCursor, since we can’t rely on the user moving the mouse?
___
The only way to unobscure the cursor is to convince the system that the mouse has moved again. There is no real good way to do this via tool calls, so you are going to have to do it the hard way and simply update the low-memory cursor information to tell the system the cursor moved (even though you do not need to update the actual position).
To tell the system the cursor has changed location, you simply set the crsrNew flag to 1; crsrNew is a byte located at $08CE. When the system sees this byte is 1 it will assume the cursor has moved, unobscure it, redraw at the appropriate place (where it was all along...) and reset crsrNew waiting for the mouse to move again, as in the following C and Pascal examples:
/* the C version... */
void UnObscureCursor ( void )
{
*(char *)0x8CE = 1;
}
(* the pascal version *)
Procedure UnObscureCursor;
begin
ptr($08CE)^:=1;
end;
This will do what you want in a short, easy-to-use package.
Macintosh QuickDraw region quirks
Written: 1/1/90
Last reviewed: 11/21/90
I’m working with regions, and I’m having problems with Macintosh QuickDraw trashing the heap and crashing, even though my regions are under 32K.
___
There are some quirks in the current version of QuickDraw. Here are some the commonly-encountered problems:
1. When doing operations which use more than one region, sduch as UnionRgn, DiffRgn, XorRgn, or SectRgn, the sum of the sizes of the source regions must be less than 32K, regardless of the size of the resulting region.
2. FrameRgn will fail if it tries to frame a region bigger than 16K.
3. If CloseRgn fails, the internal region data is already corrupt; there is nothing you can do to recover. CloseRgn will also fail if there isn’t at least a 32K block of free space available.
Here are some workarounds:
1. Keep regions small and not too complex. Keep track of the sizes of all regions so you can check the SUM of the sizes before calling a routine that has a 32K limit.
2. Keep 32K free, or allocate a 32K block and release it just before calling CloseRgn.
Apple is working on these problems and expects to fix them in future versions of QuickDraw.
How to get Macintosh QuickDraw arc endpoints
Written: 1/1/90
Last reviewed: 11/21/90
Is there a way to obtain the endpoints of an arc drawn by the Macintosh QuickDraw arc routines, such as FrameArc and PaintArc?
___
Given a rectangle R which frames the arc you wish to draw, convert your angles to an absolute coordinate system, where three o’clock is 0 degrees and 12 o’clock is 90 degrees.
Now, let:
x = .5 (+ or -) (R.right - R.left)
y = .5 (+ or -) (R.bottom - R.top)
The endpoint of the curve will be defined by:
EndPoint.h = x (+ or -) cos(ang);
EndPoint.v = y (+ or -) sin(ang);
h & v are relative to center of rectangle R
This calculates only the upper endpoint of the arc, but you can easily calculate the other endpoint using the same formula by calculating the absolute angle for the start point and applying the same formula.
Here is a subroutine which illustrates the algorithm, in LightSpeed Pascal:
{ DrawCurve: draw an arc from 0 degrees until the point defined }
{ by 'angle'. At that point draw a 4 by 4 crosshair. }
x := (frame.right + frame.left) / 2 + Num2Integer(xr);
y := (frame.bottom + frame.top) / 2 + Num2Integer(yr);
{ Draw crosshair }
MoveTo(x - 4, y);
LineTo(x + 4, y);
MoveTo(x, y - 4);
LineTo(x, y + 4);
{ Draw arc }
FrameArc(frame, 0, angle);
end;
Macintosh CopyBits no longer limited to 3K
Written: 5/3/89
Last reviewed: 11/21/90
Inside Macintosh Volume I (page 188) says there is a 3K limit for CopyBits. Is this still true?
___
The CopyBits limit is obsolete; there is no longer a 3K limit. The limit
depends on the amount of RAM in your Macintosh. CopyBits tries to use the stack to do all of the copying. In most cases CopyBits is able to copy entire screen shots at one time. You might run into problems if you don’t have enough stack to hold two times the rowBytes of your source, but even in this case CopyBits will attempt to find the memory it needs.
X-Ref:
Inside Macintosh Volume I, page 188
Why grafPort’s clipRgn should be changed before OpenPicture
Written: 11/1/90
Last reviewed: 12/19/90
On page 189 of Inside Macintosh, Volume I, in the QuickDraw chapter’s description of OpenPicture, is the following warning:
“A grafPort's clipRgn is initialized to an arbitrarily large region. You should always change the clipRgn to a smaller region before calling OpenPicture, or no drawing may occur when you call DrawPicture.”
The “arbitrarily large” clipping region rectangle is set to -32767,- 32767,32767,32767 (top, left, bottom, right) for new ports. This is the largest rectangle possible. If this is not a "valid" clipping rectangle for pictures, what is? Is there some specific limit to the size of the clipping rectangle? Does it depend on either available memory or the size of the picture?
___
Inside Macintosh ’s warning is based on truth but it’s incomplete. It didn’t actually say that this rectangle is invalid as a clipping region, because this is in fact a perfectly valid clipping region. But, you could run into problems if you use this as a clipping region when creating a QuickDraw picture. It’s not a matter of available memory or size; it’s a simple matter of 16-bit signed integer overflow and underflow.
When you open a picture, the current clip region is recorded in the picture (this wasn’t necessarily true in some early versions of QuickDraw). When you draw the resulting picture using the picture’s picFrame as the destination rectangle, there won’t be any problems. But if you use a destination rectangle that’s larger than the picFrame, QuickDraw scales everything in the picture proportionately, including the clip region. If you allowed the default clip region to be recorded into the picture, then its rgnBBox, already as large as possible, will be made even larger. That means that the -32767 coordinates might wrap around to the positive number range, and the 32767 coordinates might wrap around to the negative number range. This leaves you with an empty clip region. Nothing at all gets drawn when the current port’s clip region is empty.
If the destination rectangle is smaller than the picture’s picFrame, you won’t have any problems because the default clip region will be made smaller, and that’s no problem.
This is why Inside Macintosh suggests that you make the clip region smaller than the default clip region before opening a picture. By doing this, you’re almost guaranteed that the clip region won’t get scaled to the point that it turns inside out. What size should you make it? Small enough so that the risk of the clip region’s coordinates being scaled out of QuickDraw coordinate space is minimal. I usually just set the clip region to the picFrame of the picture. It’s hard to go wrong this way.
Macintosh CalcMask and CopyMask code sample
Written: 2/27/92
Last reviewed: 5/21/92
I can’t get the black-and-white version of my lasso-type tool to work correctly with CalcMask and CopyMask. With CalcCMask it seems to work fine. What could I be doing wrong?
___
CalcMask and CalcCMask are similar in that they both generate a 1-bit mask given a source bitmap. With CalcCMask, though, a pixMap can be used in place of the source bitmap; the seedRGB determines which color sets the bits in the mask image. An easy mistake to make is to forget that CalcCMask accepts a pointer to a bitmap data structure while CalcMask expects a pointer to the actual bit image. And unlike CalcCMask, which uses bounding Rects for the image’s dimensions, CalcMask uses the bitmap’s rowBytes and pixel image offsets to determine the bounding Rects for the image. A typical call to these routines would be
One last thing to note when using CalcMask is that the width of the image is in words and not bytes. To learn more about these routines, see page 24 of Inside Macintosh Volume IV and page 72 of Inside Macintosh Volume V. Also, the Developer CD Series disc contains a sample, CalcCMask&CalcMask, that shows how to use both these routines.
Macintosh QuickDraw LineTo bug and workaround
Written: 4/23/92
Last reviewed: 7/13/92
Our zooming function crashes into flames when we pass valid coordinate values to LineTo, as in the following example:
SetPort(myPort);
MoveTo(154,31619);
LineTo(74, -31742); (* You are dead! *)
What can we do to avoid LineTo crashes like this?
___
The QuickDraw Engineering group is aware of the problem you described. The bug probably is going to be fixed in the next release that includes bug fixes. Given that waiting for a system solution may demand more patience than is reasonable, you may want to consider including in your software some form of workaround that will prevent your users from crashing every time an operation takes the software to the limits of QuickDraw.
One way to approach this problem is to replace the lineProc bottleneck. All you need to do is to check the distance between the current pen position and the line’s end, and when the distance becomes too big (let’s say more than 32000) your procedure will call StdLine a couple of times, splitting the operation in two.
Replacing the bottlenecks is a very straightforward operation (which you are probably already using) and in most of the cases will only result in another level of indirection into StdLine but that will prevent your program from calling QuickDraw with parameters that are guaranteed to cause crashes.
QuickDraw globals at INIT time
Written: 6/1/92
Last reviewed: 9/15/92
If I call InitGraf before I reference CurrentA5, will CurrentA5 be valid and can the QuickDraw globals be referenced off it? The screenBits bounds values seem screwy on some machines. Does the problem lie with CurrentA5? Should I be referencing A5?
___
Here’s the process used by ShowINIT, which is remarkably compatible with system software and other INITs (and it had better be, because it’s used by more than half the system extensions available):
1. It saves the value in the CurrentA5 global to restore it later.
2. It points the A5 register at 4 bytes of storage for use by the system.
3. It copies the value now in A5 into the CurrentA5 global.
4. It calls InitGraf, passing a pointer to the thePort field of a QuickDraw globals structure.
5. It opens a port and draws as necessary. [This is where all the functionality goes.]
6. After it’s done, it closes its port.
7. It copies the value saved in step (1) into the A5 register.
8. It copies the restored A5 value into the CurrentA5 global.
To summarize, ShowINIT saves the A5, creates and initializes its own A5 world, does its drawing, then restores the previous A5 world. For more information on this subject, see the Macintosh Technical Note “Stand-Alone Code.”
So Many Bitmaps, So Little Time
Imaging M.IM.BitMatToRegion
Revised by: Rich Collyer December 1989
Written by: Rick Blair April 1988
This Technical Note discusses the routine BitMapToRegion, which converts a bitmap to a region, and is available in the 32-Bit QuickDraw INIT and from Apple Software Licensing.
Changes since October 1989: Added trap definitions for developers using the 32-Bit QuickDraw version of this routine without the correct MPW include file.
The following routine is now available to convert a bitmap to a region:
FUNCTION BitMapToRegion(region:RgnHandle; bMap:BitMap): OSErr;
If you are using the 32-Bit QuickDraw version of this routine without the correct MPW include file, then you need to include one of the following definitions:
Pascal
FUNCTION BitMapToRegion (region: RgnHandle; bMap: BitMap): OSErr;
The region will be built so that all one bits in bMap are inside the region and all zero bits are outside of it.
As with all QuickDraw calls which change a region, BitMapToRegion requires you to pass an existing region (originally created by _NewRgn). If the region cannot be built due to an insufficient heap space or a size greater than 32K, then the routine will return an appropriate error code and the region will be empty. If the region would have exceeded 32K, the error will be rgnTooBigErr (-500).
This function is useful for a number of situations where you have (or can produce) a bitmap representing an area. You can use _CalcMask to produce such a bitmap. Once you have a region, you can perform region operations (i.e., _PtInRgn, _UnionRgn, or _InsetRgn) or call _DragGrayRgn, for example.
This call is part of the 32-Bit QuickDraw INIT ($A8D7). If you do not wish to depend on 32-Bit QuickDraw, then you can obtain a version of BitMapToRegion in MPW object format which can be linked into an MPW program, by contacting Apple Software Licensing:
Apple Software Licensing
Apple Computer, Inc.,
20525 Mariani Avenue, M/S 38-I
Cupertino, CA, 95014
(408) 974-4667
AppleLink: SW.LICENSE
If you licensed the older version of this routine, BitMapRgn, contact Software Licensing about receiving an updated version. We recommend you update your application to use the new version as soon as possible.
The new version is now named BitMapToRegion to be consistent with the version in 32-Bit QuickDraw and the MPW interfaces. In addition, BitMapToRegion offers new features. You can now pass a one-bit pixelmap which has been coerced to a bitmap. If you pass a pixelmap which is too large, then you will get a pixmapTooDeepErr (-148) error. You can also pass the portBits of a window, much like you would do with a call to _CopyBits.
There is a potential problem with this routine, since MPW 3.1 include files contain information about 32-Bit QuickDraw. If you want BitMapToRegion to be available on all machines, then you must use the object file from Software Licensing. The problem is that when you compile your application with MPW 3.1 or later, the 32-Bit QuickDraw version gets preference over the object file. You must comment out the routine in the include files if you want to use the object file. If you only care about using BitMapToRegion on machines running 32-Bit QuickDraw, then you need not do anything.
A Leading Cause of Color Cursor Cursing
Imaging M.IM.ColorCursor
Revised by: Alan Mimms October 1989
Written by: Alan Mimms June 1989
Working with color cursors you create from scratch can cause headaches. This Technical Note may help a bit.
Changes since June 1989: Added a warning about purgeable 'clut' resources.
If you’re building an application that creates color cursors, you may encounter some quirks present in Color QuickDraw that manifest themselves in hard-to-understand ways.
If your cursor is, say, 15 pixels tall and 9 pixels wide, you might be tempted to use these values for the bounds.bottom and bounds.right, respectively, in your cursor’s pixel map. Don’t. The problem is that when the cursor’s image needs to be expanded (i.e., when you specify a two bit-per-pixel cursor and the mouse pointer is on an eight-bit screen) the _SetCCursor trap rounds the width of the pixel map in such a way that you’ll get only the space required for a 15 by 8 pixel map allocated for the expanded cursor data. When the cursor’s image is expanded into this too-small expanded cursor data handle as a 15 by 9 pixel map, something in your heap will get munched.
The cure is simple. Make certain that you always specify that the pixmapHandle^^.bounds be 16 by 16. This will cause _SetCCursor to properly allocate the expanded data area, and all will be well in the land. Since the amount of data drawn for a cursor is specified by the cursor’s pixel values and 'clut' resource, trying to save a few bytes by making the bounds rectangle smaller than 16 by 16 wouldn’t have been very helpful anyway.
Another potential problem is with the color cursor’s color table. If you load the color table from a 'clut' resource using _GetCTable, you should make sure that the 'clut' is marked non-purgeable while the color cursor is in use. If you do not take this precaution, bombs will occur if your 'clut' gets purged at in inopportune time.
Color Manager Q&As
Imaging M.IM.ColorMgr.Q&As
Revised by: Developer Support Center October 1992
Written by: Developer Support Center October 1990
This Technical Note contains a collection of Q&As relating to a specific topic—questions you’ve sent the Developer Support Center (DSC) along with answers from the DSC engineers. While DSC engineers have checked the Q&A content for accuracy, the Q&A Technical Notes don’t have the editing and organization of other Technical Notes. The Q&A function is to get new technical information and updates to you quickly, saving the polish for when the information migrates into reference manuals.
Q&As are now included with Technical Notes to make access to technical updates easier for you. If you have comments or suggestions about Q&A content or distribution, please let us know by sending an AppleLink to DEVFEEDBACK. Apple Partners may send technical questions about Q&A content to DEVSUPPORT for resolution.
New Q&As and Q&As revised this month are marked with a bar in the side margin.
Color Manager search and complement procedures
Written: 10/7/91
Last reviewed: 11/6/91
The AddComp complement procedure description in Inside Macintosh Volume V, pages 145-147, is vague. The last paragraph on page V-146 states, “Complement procedures work the same as search procedures,” but SearchProc is a function, CompProc is a procedure, and each have a different number of parameters. What else does CompProc need as input and on exit?
___
CompProc should be declared as a Pascal FUNCTION that returns a Boolean. The code performs a CLR.B for the return value of CompProc, so treat it like SearchProc. CompProc only uses one parameter since its one parameter is a VAR, which means it will be replaced with the correct complementary color. SearchProc returns an index in its second parameter, which is why it needs a second parameter.
Using ResEdit to get Apple icon RGB values
Written: 1/7/92
Last reviewed: 8/1/92
I am trying to find the RGB values for Apple's standard icon colors. I can’t find this information in any documentation. Is this information available?
___
While the RGB values for the standard Apple icon colors (and other standard palette colors) are not explicitly documented, they are easy to obtain with ResEdit 2.1.1. In any resource file, create and open a new 'pltt' resource. Choose Load Colors from the pltt menu and pick Apple Icon Colors, and a standard palette will be created. Selecting a color will reveal its component values.
ResEdit 2.1.1 is available on the latest Developer CD Series disc and from APDA.
Macintosh Color Manager versus Palette Manager
Written: 1/1/90
Last reviewed: 8/1/92
When should the Macintosh Color Manager be used and when should the Palette Manager be used?
___
The Palette Manager is by far the friendlier and more versatile of the two if your application uses different colors than the default system colors. It provides all the functionality you need to customize and animate the colors in your application. You shouldn’t ever need to use the Color Manager unless you require custom color search and complement functions. When using the Palette Manager, applications will maintain their respective color environments safely as they move back and forth from foreground to background, and from one screen to another. Accomplishing this with the Color Manager calls is not worth the effort or very safe. For additional information, see the Palette Manager chapter in Inside Macintosh Volumes V and VI.
Color QuickDraw Q&As
Imaging M.IM.ColorQD.Q&As
Revised by: Developer Support Center December 1992
Written by: Developer Support Center October 1990
This Technical Note contains a collection of Q&As relating to a specific topic—questions you’ve sent the Developer Support Center (DSC) along with answers from the DSC engineers. While DSC engineers have checked the Q&A content for accuracy, the Q&A Technical Notes don’t have the editing and organization of other Technical Notes. The Q&A function is to get new technical information and updates to you quickly, saving the polish for when the information migrates into reference manuals.
Q&As are now included with Technical Notes to make access to technical updates easier for you. If you have comments or suggestions about Q&A content or distribution, please let us know by sending an AppleLink to DEVFEEDBACK. Apple Partners may send technical questions about Q&A content to DEVSUPPORT for resolution.
New Q&As this month:
Disabling Macintosh Color QuickDraw for testing
Disabling Macintosh Color QuickDraw for testing
Date written: 9/14/92
Last reviewed: 11/1/92
Is there an easy way to disable Color QuickDraw on a Macintosh? I want to do this for testing our application, to make sure it works correctly on a machine without Color QuickDraw.
___
There’s no easy, or perhaps even hard way to disable features built into the system software your particular machine requires. It’s designed to work well, not to be toggle-able.
Even the hard way isn’t a sure thing—trying to patch out all the Color QuickDraw traps could confuse the rest of the system software, which internally may use undocumented routines to accomplish its tasks.
The easiest way to test on non-Color QuickDraw machines is to get one. Fortunately, the machines without Color QD are the lowest end of the Macintosh price spectrum—such as the Macintosh Classic, PowerBook 100, and Macintosh SE. You can probably rent or borrow one of these if the prices don’t fit your current budget.
Using a Macintosh PICT file that’s larger than available memory
Written: 6/18/90
Last reviewed: 9/24/91
How can I read a 2 MB PICT file into only 1 MB of memory?
___
You can’t read it in since you don’t have enough memory, but drawing the picture contained in the file using a technique called “spooling” increases your chances of using a 2 MB PICT file with 1 MB memory. Spooling is documented in the Color QuickDraw chapter of Inside Macintosh Volume V (pages 88–89).
Getting a single scan line from a PICT file
Written: 6/18/90
Last reviewed: 9/24/91
Is there any way to obtain a particular scan line from a PICT file?
___
A PICT file may contain more than just pixmaps, so getting one scan line out of it is not possible. The file may also contain other elements that overlap, such as rects and arcs. The only way to obtain a single line is to draw it off-screen and then, once the whole image is in memory, you can go and study individual pixels.
Determining pixel depth from PICT files
Written: 6/20/90
Last reviewed: 9/17/91
How do you find out the pixel size of a PICT file on the disk?
___
A picture is by nature independent of depth. For example, you can have a picture containing DrawRects and LineTos and therefore lacking any info regarding depth.
On the other hand, if the picture you are looking at has pixmap opcodes in it, then each pixmap contains its own pixel size and in this case a picture can have a number of depths associated with it.
If you want to see the pixel size for each pixmap opcode in a picture, replace all the bottleneck routines and every time the bitsProc is called you can see the pixmap and get the info out. Since the picture is in a file, you can use the spooling technique described in the QuickDraw chapter in Inside Macintosh Volume V. Be ready to deal with multiple, possibly different, pixmaps as well as direct pixmaps if the picture was created under 32-bit QuickDraw.
”KnowsPICT,” on the Developer CD Series disc, extracts this kind of information. The System 7.0 Picture Utilities package gets this information too.
Direct RGB PICT file compression
Written: 10/24/90
Last reviewed: 2/14/91
How are bits packed in direct RGB PICT files created by 32-Bit QuickDraw? I looked at the Macintosh Technical Note “Things You Wanted to Know About _PackBits…”, but this run-length encoded compression is clearly inefficient for cases where pixelSize is greater than 8 bits. I write software for machines other than Macintosh that decodes PICT files; therefore, I cannot issue any QuickDraw calls such as _unpackBits.
___
You’re quite right; compressing direct pixels using straight run-length encoding doesn’t work very well. Fortunately, direct pixel maps aren’t compressed this way. Compression schemes are discussed in Inside Macintosh Volume VI in the section titled “The New OpCodes: Expanded Format.”
In short, if the packType field holds the value 1, then no compression is done at all. The complete pixel image is saved in the PICT. If the packType field holds the value 2 and the pixel map is 32-bits per pixel, then all that’s done is that the alpha-channel byte is removed. So this:
00 FF FF FF 00 FF FF FF
is compressed to:
FF FF FF FF FF FF
If the packType field holds the value 3 and the pixel map is 16 bits per pixel, then run-length encoding is done, but not through PackBits. Instead, a run-length encoding algorithm private to QuickDraw is used. This algorithm is very similar to PackBits, but where PackBits compresses runs of bytes, this routine compresses runs of words. The format of the resulting data is exactly the same as described in the Technical Note “Things You Wanted to Know About _PackBits…”, but you’ll get words instead. To build on the example in this Tech Note, lets say the 16-bit pixel image begins with these pixel values:
where the asterisks mark the flag-counter bytes. Notice that you can’t assume that the pixel values are word-aligned. PackBits packs data 127 bytes at a time, though it will do this for up to 32,767 total bytes. Similarly, the internal compression routine packs data 127 words at a time.
If the packType field holds the value 4 and the pixel map is 32-bits per pixel, then run-length encoding via PackBits is done, but only after some preprocessing is done. QuickDraw first rearranges the color components of the pixels so that each color component of every pixel is consecutive. So the following four pixels (the row below the pixel values indicates a = alpha channel, r = red, g = green, b = blue, and the pixel offset):
00 FF FF FF 00 FF C0 00 00 FF 80 00 00 C0 80 00
a0 r0 g0 b0 a1 r1 g1 b1 a2 r2 g2 b2 a3 r3 g3 b3
is rearranged to become:
FF FF FF C0 FF C0 80 80 FF 00 00 00
r0 r1 r2 r3 g0 g1 g2 g3 b0 b1 b2 b3
The first four bytes are the red components of the four pixels, the next four bytes indicate the green components of the four pixels, and so on. The alpha channel isn’t included unless the cmpCount field contains 4 rather than the normal 3. If cmpCount contains 4, then all the alpha channel bytes are placed before the red bytes. Once this is done, then PackBits is called to compress the rearranged data.
Those are the only four compression schemes (including no compression) that are supported for direct pixel maps in PICTs. As always, reading PICTs yourself puts you in danger of not being able to read PICTs generated by future versions of QuickDraw. For compatibility reasons, these compression algorithms as I’ve described them probably can’t change in the future. It’s possible that new values for packType could be implemented though.
X-Ref:
Macintosh Technical Note “Things You Wanted to Know About _PackBits…”
Saving 32-bit Macintosh PICTs
Written: 10/30/90
Last reviewed: 2/20/91
I am using a packType=4 and have several questions about saving Macintosh 32-bit images in a PICT format:
1. What are the ramifications of using cmpCount=3 as opposed to cmpCount=4?
2. How is the pixData actually stored? According to several references, each line is run-length encoded; that is, [byteCount][data]. If rowBytes>250 then byteCount is a word. After looking at several examples, I came to the conclusion that you are actually using PackBits and that the term “run-length” encoded is a misnomer.
___
1. The difference between using cmpCount=3 or cmpCount=4 is that in the first case only the R, G, and B values are stored in the picture; in the second case QuickDraw stores in the picture the alpha channel plus R, G, and B. cmpCount=4 can be used when it is important to also save the alpha channel (as when you have some flags stored there).
2. Unless rowBytes is less than 8, the pixmap is compressed using PackBits, and the length is a word or a byte depending on rowBytes, but it always refers to the number of bytes comprising one scan line. My guess is that “run-length encoding” refers to the fact that pictures have data organized one row at a time.
To show how direct RGB pixmaps are stored inside a picture, I am including the decoding of a picture that I created to show how the different packing schemes change the resulting pixmap opcode data. First I created a direct RGB pixmap and drew three lines into it. The first line is 8 pixels long with a color of {0x1111,0xAAAA, 0x7777}, the third line is 8 pixels of {0xFFFF, 0x3333, 0xBBBB} and the line in between is two pixels of the first color then two pixels of the second color and so on until you make 8 pixels. Then I created a picture made of CopyBits calls copying the same lines but using different packing schemes. Finally I dumped the contents and the result is what you see here. I have put comments I think help make it clear how the packing scheme of choice changes the results.
I recommend that you have the Inside Macintosh Volume V QuickDraw chapter at hand to check the opcodes and data associated with them. If you had Inside Macintosh Volume VI then you wouldn’t need to also check the 32-Bit QuickDraw docs for the direct RGB pixmap opcodes. The Technical Note “Things You Wanted To Know about _PackBits…” gives details on how the packed data is arranged.
0256 0000 0000 0008 0008 /* size and rect */
0011 02FF 0C00 FFFF FFFF /* PICT2 Header */
0000 0000 0000 0000 0008
0000 0008 0000 0000 0000
001E /* Default hilite */
001A FFFF 3333 BBBB /* RGB Fore Color */
0001 000A 8001 8001 7FFF 7FFF /* ClipRgn */
009A /* direct pixels opcode; see IM VI QD chapter for details */
0000 00FF 8020 0000 0000 0003 0008 0000 /* See IM V or VI QuickDraw chapter
Macintosh Technical Note “Things You Wanted To Know about _PackBits…”
BitMapToRgn for non-Color QuickDraw Macintosh models
Written: 11/9/90
Last reviewed: 2/20/91
Is _BitmapToRegion available on any pre-System 7 non-Color QuickDraw configurations such as the Macintosh Classic, Plus, or SE? If not, is source or a library module available so that I don’t have to take the time and compatibility risk of rolling my own?
___
BitMapToRegion works on pre-color Macintosh systems. You can license BitMapToRegion from
Software Licensing
Apple Computer, Inc.
20525 Mariani Ave. MS:38-I
Cupertino, CA 95014
AppleLink: SW.LICENSE
Phone:(408) 974-4667
Macintosh QuickDraw pixel map stack requirements
Written: 12/3/90
Last reviewed: 5/21/91
What are the guidelines for determining how much of an image CopyBits can copy to a Macintosh pixel map at one time, given a particular set of characteristics for the source map and the destination map and given how much stack space is available? For example, say that we have an 8-bit-deep pixmap to be copied to a 32-bit-deep pixMap using the ditherCopy mode and expanded by a factor of 4, and we have 45K of stack space.
___
CopyBits’ stack requirement depends on the width of each scan line (rowBytes). The rule of thumb is that you need at least as much stack as the rowBytes value in your image (which can be huge with 32-Bit QuickDraw), with the following additional modifiers: Add an additional rowBytes for dithering; add an additional rowBytes for any stretching (source rect != dest rect); add an additional rowBytes for any color map changing; add an additional rowBytes for any color aliasing. The stack space you need is roughly five times the rowBytes of your image. In general, you’re better off processing narrower scan lines. Reducing the vertical size will not affect stack requirements. Narrow, tall bands (if you can use them) will reduce the stack requirements.
Color and non-Color QuickDraw trap dispatch differences
Written: 1/28/91
Last reviewed: 2/13/91
Why does a call to RGBForeColor cause a corruption of the stack without resulting in an unimplemented trap error on non-Color QuickDraw Macintosh systems?
___
The trap dispatcher on Color QuickDraw and non-Color QuickDraw machines are different. If you look at page 89 of Inside Macintosh Volume I, you’ll see the toolbox trap word format as it was in the days before Color QuickDraw. Bit 9 was “reserved for future use” and was ignored by the trap dispatcher, and so it was normally set to 0. That means that valid toolbox traps could either look like $A8XX or $A9XX as long as the auto-pop bit was turned off. Color QuickDraw machines have a trap dispatcher that uses that reserved bit to allow for more trap words, and therefore it has a much larger trap dispatch table. Color QuickDraw traps have that reserved bit set, so those traps look like $AAXX or $ABXX.
When a non-Color QuickDraw machine tests to see if a trap is implemented or not, it just checks the trap dispatch table to see if a routine is implemented for that trap or not. Because the reserved bit is ignored, trap words that look like $AAXX are treated as equivalent to $A8XX and trap words that look like $ABXX are treated as equivalent to $A9XX. The trap word for RGBForeColor is $AA14. If you call RGBForeColor on a non-Color QuickDraw machine, $AA14 is treated as $A814, which is the trap word for SetFractEnable. SetFractEnable is implemented on 128K ROM machines or greater, so no unimplemented trap error occurs.
If you look at recent DTS sample programs, such as the Utilities sample (SC.025.Utilities, which you can find on AppleLink in Developer Support and on the current developer CD), you’ll see a routine in Utilities.c called TrapExists. It takes into account the size of the trap dispatch table so that you can tell in one call whether a routine is implemented or not regardless of whether it’s a Color QuickDraw trap or not and regardless of what kind of Macintosh you’re running on.
Under system software version 7.0, the trap dispatcher is modified on non-Color QuickDraw machines so that many Color QuickDraw traps are implemented and work as well as they can in black and white.
Macintosh OpenCPicture 72-dpi calculation bug
Written: 2/12/91
Last reviewed: 2/20/91
The 32-Bit QuickDraw _OpenCPicture call incorrectly calculates the 72-dpi frame width if the height of the native resolution srcRect exceeds 910 dots. To work around this problem, I calculate the 72-dpi frame independently, and store it in the PicHandle returned by _OpenCPicture.
___
It’s a known bug that under Macintosh system software versions 6.0.5 and 6.0.7 with 32-Bit QuickDraw 1.2, OpenCPicture doesn’t properly calculate the right coordinate of the 72-dpi picFrame if the height of the srcRect (native resolution rectangle) multiplied by 72 exceeds $0000FFFF. That works out to a maximum height of 910 pixels, just as you found. This bug is fixed in System 7.0, but gestaltQuickdrawVersion returns $0220 both under system software versions 6.0.5 and 7.0, so you can’t tell whether the bug is fixed that way. Instead, you should use Gestalt with the gestaltSystemVersion selector. If the returned value is $0700 or greater, then let OpenCPicture handle the picFrame calculation; otherwise you should do the calculation yourself.
GetGWorldPixMap bug and workaround
Written: 3/12/91
Last reviewed: 10/9/91
Why does GetGWorldPixMap (when called on a Macintosh II, IIcx, or IIx running system software version 6.0.5 or 6.0.7 with 32-Bit QuickDraw 1.2) return a combination of the device field (two bytes) and the first two bytes of the portPixMap field? Is this a bug?
___
Your analysis of GetGWorldPixMap is exactly right: It doesn’t work correctly in system software versions 6.0.5 and 6.0.7 with 32-Bit QuickDraw 1.2. It returns a value that’s two bytes before the value it’s supposed to return.
The solution is to use GWorldPtr->portPixMap instead of GetGWorldPixMap. It’s safe to do this, but you should use GetGWorldPixMap under System 7. Not only is the bug fixed there, but dereferencing the port is dangerous under System 7 because it may not be CGrafPort. Use Gestalt with the gestaltQuickdrawVersion selector to determine whether you can use GetGWorldPixMap. If Gestalt returns a value from gestalt8BitQD ($0100) through gestalt32BitQD12 ($0220), then GetGWorldPixMap either doesn’t exist or is the buggy version. If it returns gestalt32BitQD13 ($0230) or higher, then GetGWorldPixMap does exist and works correctly. Interestingly, GetGWorldPixMap can be called on a black-and-white QuickDraw machine under System 7. It returns a handle to a structure that should be treated as a bitmap structure, though there are some undocumented fields after the normal bitmap fields. To tell whether GetGWorldPixMap is available on a black-and-white QuickDraw machine, you must check the system software version by calling Gestalt with the gestaltSystemVersion selector. If it returns $0700 or higher, GetGWorldPixMap is available.
System 7 TextMode problem and workaround
Written: 6/12/91
Last reviewed: 8/13/91
Our application uses the TextMode (blend + mask) as documented in Inside Macintosh Volume V (blend is equal to the current ditherCopy constant) to make translucent text. Under System 7, this transfer mode causes garbage to appear when the text is drawn. Is there a way to work around the problem? Will there be a fix?
___
The problem you are seeing is due to the use of CopyDeepMask instead of the old-fashioned CopyBits to do the job. It is being studied now, and the hope is that it will work as advertised in a future release. One workaround is to render the text to an off-screen pixmap and then call CopyBits (using blendMode) to actually put it in the picture.
Using dithering and animation on the same Macintosh image
Written: 6/19/91
Last reviewed: 10/15/91
When setting up a dithered grayscale image for subsequent animation (to adjust brightness, for example), a conflict arises between the use of Palette animation and the ditherCopy CopyBits mode. This problem is demonstrated in the develop #5 GiMeDaPalette code sample: If you change srcCopy to ditherCopy in the CopyBits call, then run the program and select Animate, the resulting image is pure black and white, with what appears to be an attempt to dither with just the black-and-white color table entries (that are not reserved for animation).
This happens because ditherCopy tries to use the inverse table to do color matching, but when the image is animated, the inverse table colors are limited to just black and white.
To work around the problem, you can jump into the bottlenecks and when you see the PICT hitting the opcode for CopyBits, change the PICT from a srcCopy to a ditherCopy. This way the dithering happens when you do the call to DrawPicture and not later on. This makes it possible to use dithering and animation on the same image.
Rendering color PICTs in a black-and-white environment
Written: 7/22/91
Last reviewed: 9/17/91
I want to be able to render a color PICT as a black-and-white image substituting patterns for colors. My images are pretty small and have fewer than 16 colors. What do you suggest as the easiest way?
___
One easy way is to take advantage of 32-Bit QuickDraw and System 7.0’s ditherCopy transfer mode modifier or flag (documented in Inside Macintosh Volume VI, page 17-17). Call DrawPicture into an off-screen pixmap with the pixel depth of the original color PICT. Then call CopyBits to copy the pixmap to the screen, with srcCopy + ditherCopy as the transfer mode. This will result in a nicely dithered image on the black-and-white end.
Under System 6 without 32-Bit QuickDraw, the solution is not nearly so cut and dried. One way might be to take advantage of the fact that DrawPicture goes through the QuickDraw bottlenecks for drawing. For each grafproc in your PICT, you’d intercept StdBits during DrawPicture and call your own dithering routine to examine the foreground color and set the pen pattern or fill pattern so that it has about the same lightness as the original color.
Well, this came out as a great sales pitch for writing a System 7-savvy app!
Highlighting ignored if foreground same as background color
Written: 8/7/91
Last reviewed: 9/24/91
Under System 7, but not System 6, HiliteColor is not used for InvertRect when the hilite bit is set and the background is exactly black (R=G=B=$0000). Also, HiliteColor doesn’t draw when a pen mode of XOR is used in a LineTo call.
___
The problem you encounter exists whenever the background and foreground colors are the same when using highlight mode. If the foreground color is the same as the background color, highlighting is ignored. Therefore, when you set the foreground color to white, you should set the background color to something other than the default color of white.
Gestalt 'qdrw' selector bug and workaround
Written: 8/1/91
Last reviewed: 10/9/91
Why does Gestalt tell me I have Color QuickDraw features on a non-Color QuickDraw machine?
___
The gestaltQuickdrawFeatures ('qdrw') selector, used for determining your system’s Color QuickDraw features, has a bug that causes it to tell you incorrectly that noncolor machines have color. The fix is quite simple: Gestalt has another selector, gestaltQuickdrawVersion ('qd '), which simply returns the QuickDraw version number. This version number is < gestalt8BitQD for classic QuickDraw and >= gestalt8BitQD for Color QuickDraw (see Inside Macintosh Volume VI, page 3-39, for more information). The trick is to ask Gestalt for the QuickDraw version first; once you’ve determined that you have Color QuickDraw, the 'qdrw' selector is OK to use to find out specifics.
Version 2 PICTs on pre-Color QuickDraw models
Written: 8/13/91
Last reviewed: 10/22/91
Inside Macintosh Volume V says a System 4.1 (and later) patch ensures that version 2 PICTs are displayed correctly on earlier machines that don’t have Color QuickDraw, such as the Macintosh Plus and SE. However, my version 2 PICT, consisting primarily of a pixmap (opcode = $90 since rowBytes <8) displays correctly on a Macintosh IIfx but displays garbage on a Macintosh SE.
___
The PICT problem you reported is caused by a bug in 6.0.7 QuickDraw. The workaround for the time being is to:
• Use System 7.0, where it’s been fixed, or
• Don’t use opcode $90. Instead, use padding so that opcode $98 can be used. (Opcode $98 is the packed CopyBits version that works for rowBytes >= 8.). You can do this by creating the picture with a pixmap that’s wider than you actually need, and then use the clip region to clip out the part you don’t need.
GetPixelsState is slow sometimes
Written: 8/27/91
Last reviewed: 9/24/91
Why do I sometimes see incredible slowdowns under System 7.0 when calling either GetPixelsState or LockPixels (I’m not sure which) for the PixMapHandle of a GWorld allocated in temporary memory?
___
GetPixelsState takes an arbitrary amount of time since it makes a call to RecoverHandle to get the handle pointing to the baseaddr. Therefore, the slowdown you see as actually due to the call to RecoverHandle, which is slow because it must traverse the heap to find the pointer to the baseaddr. LockPixels is not responsible for the slowdown because it does not make call to any traps that could take an extended amount of time.
OpenCPicture and PICTs other than 72 dpi
Written: 10/2/91
Last reviewed: 10/8/91
Can I use OpenCPicture to create PICTs with a higher resolution than 72 dots per inch (dpi)?
__
There’s good news and bad news: The good news is that you’re on top of the situation, which means the bad news is that there aren’t better ways to do what you want to do, mostly. Here’s the scoop:
You can use vRes and hRes in pictures opened with OpenCPicture to tell QuickDraw it’s not a 72-dpi picture, and as long as the application that receives the picture uses DrawPicture to image it, QuickDraw will Do The Right Thing—scaling it on the screen to 72 dpi instead of making it humongously large. Unfortunately, this way you lose hairlines; if you print such a picture to a 72-dpi grafPort (like the LaserWriter driver normally returns), you’ll get 1/72-inch lines instead of 1/300-inch lines as you probably want.
(This can work correctly, but the receiving application has to notice that your picture is bigger than 72 dpi and ask PrGeneral to increase the resolution of the printing grafPort accordingly, and this doesn’t always or often happen.)
No System 7 QuickDraw alpha channel support
Written: 10/23/91
Last reviewed: 11/27/91
How can I directly access the alpha channel (the unused 8 bits in a 32-bit direct pixel using QuickDraw) under System 7? Under System 6 it was easy, but under System 7’s CopyBits() the alpha channel works with srcXor but not with srcCopy.
___
With the System 7.0 QuickDraw rewrite, all “accidental” support for the unused byte was removed, because QuickDraw is not supposed to operate on the unused byte of each pixel. QuickDraw has never officially supported use of the extra byte for such purposes as an alpha channel. As stated in Inside Macintosh Volume VI, page 17-5, “8 bits in the pixel are not part of any component. These bits are unused: Color QuickDraw sets them to 0 in any image it creates. If presented with a 32-bit image—for example, in the CopyBits procedure—it passes whatever bits are there.”
Therefore, you cannot rely on any QuickDraw procedure to preserve the contents of the unused byte, which in your case is the alpha channel. In fact, even CopyBits may alter the byte if stretching or dithering is involved in the CopyBits by setting them to zero. Therefore, the only possible workarounds for this problem are to not use the unused byte for alpha channel storage since the integrity of the data cannot be guaranteed; or, to not use QuickDraw drawing routines which can alter the unused byte.
BitsToRgn and MPW BitMapToRegionGlue
Written: 10/29/91
Last reviewed: 12/11/91
Which version of the system software first contained the call BitsToRgn? Is there a workaround for this call if my users have an earlier version of system software?
___
The call BitmapToRegion was introduced with 32-Bit QuickDraw and became fully documented in Volume VI of Inside Macintosh, which is primarily System 7 information. However, since the differences between System 7’s QuickDraw and 32-Bit QuickDraw are minor, most of System 7’s QuickDraw routines are available in system software prior to System 7.0 using the 32-bit QuickDraw INIT.
To check to see if a system contains 32-bit QuickDraw, you can use the following snippet of code:
/* Find out if GWorlds and CQD are implemented on this machine */
If you are using MPW as a development platform, MPW has a library call you can use that will allow you to use the routine regardless of whether or not 32-bit QuickDraw exists. The glue routine is called BitMapToRegionGlue() and is available to MPW users. Substitute this call for BitMapToRegion calls and the glue code will take care of patching in the proper code if 32-bit QuickDraw does not exist. If you’re using Think C, you can use the oConv utility to convert the MPW object file into a Think C usable format.
Ensuring even rowBytes for 'cicn' resources
Written: 12/4/91
Last reviewed: 1/27/92
Is there any way to force bitmaps and masks within a 'cicn' resource to have an even rowBytes (using ResEdit)? I want to avoid duplicating icon bitmaps—one for color systems set to B&W and one for B&W systems—to reduce program size as well as development and maintenance costs. The bitmaps in the 'cicn' can also be sized specifically to the task, whereas the old B&W icons are of a fixed size and contain no sizing information. It’s simple enough to read in a 'cicn' and extract the bitmap. The problem is that on a 68000 (no Color QuickDraw), if rowBytes is odd, an odd address trap results.
___
There isn’t any way to get ResEdit itself to create bitmaps with even rowBytes for 8 x 8 'cicn' resources, but here are few suggestions:
You could process your 'cicn' resources first, so that they have bitmaps as you require them. To alter the resource with a quick little program would be trivial, especially given that the bitmap data sits last in the 'cicn'. All you’d need to do is expand the bitmap image data by padding each line to an even length and then changing the rowBytes value. Or you could de-rez the 'cicn's and patch them with a text editor, either by hand or with a search-and-replace script of some kind.
I have two gray-colored pixmaps that I wish to blend together; one is on the screen, the other in an off-screen pixmap. I use CopyBits to copy the off-screen to the screen, but it does not seem to blend them. Instead, it seems to match the colors of the screen bitmap to the closest colors in some table, thus having the effect of reducing the number of colors displayed on the screen bitmap. Any suggestions?
___
There are two distinct questions here: 1) Why ain’t it blending? and 2) What’s this banding for? The first problem is almost certainly because OpColor isn’t set properly. This is a third, implicit, operand on several arithmetic graphics operations, including blend. For blend, it describes the proportions to mix the source and destination colors in the blend. For an equal mix, you should set this color to a halfway gray. (Call OpColor() with a color where red, green, and blue all equal $8000.) This effect is described in the description of the blend mode on page 60 of Inside Macintosh Volume V. Unfortunately, the initial value for OpColor is black (0,0,0), so you were seeing no mixing of your off-screen data.
The second half of your question is why you’re getting a banding effect. (When you fix the above problem, you’ll still get banding.) Unfortunately, the arithmetic modes are constrained by the size of the inverse table. As your screen no doubt uses the default 4-bit inverse table, you’ll find that you’ll get only 2^4 = 16 levels of gray. If you enlarge your screen’s inverse table to 5 bits, the maximum allowable, you’ll still only get 32 gray levels. (To do this, set the gdResPref field in the GDevice to 5, then call MakeITable().) The only way to get a fully-gradual, great-looking effect is to do all the work off-screen in 24-bit deep pixmaps, and then copy it to the screen. Because they can operate directly on colors, rather than having to work through the intermediary of color indices, direct pixmaps are not limited by inverse tables (in fact, they don’t even have real inverse tables). You could use 16-bit pixmaps, but they only provide 32 grays (having only 5 bits for each component), so this wouldn’t be any better than increasing the size of the inverse table.
Icon dimming under System 7 and System 6
Written: 1/6/92
Last reviewed: 2/6/92
When you bring up the Control Panels window under System 7 on a color system and click a control panel item icon, it paints itself that fancy gray. How can I get that effect?
___
To get the fancy System 7 icon dimming to work in your program, use the icon drawing routines PlotIconID or PlotCIconHandle with an IconTransformType of ttSelected. Both of these routines and their transform types are used by the control panel and are described in the Macintosh Technical Note “Drawing Icons the System 7 Way.”
If you want the same effect under System 6, you’ll have to emulate the dimming of the icons via QuickDraw, by installing a color search proc to dim the RGB values that the icon uses. On page 146 of Inside Macintosh Volume V is a description of how to define and install your custom search proc.
QuickDraw out of memory if debugger invoked by “Jackson”
Written: 3/11/92
Last reviewed: 4/7/92
I am getting a strange bug in which the Macintosh debugger is being invoked by an A-trap marked “Jackson” when I call SetCCursor in certain situations and a second monitor is hooked up. The cursor structure being passed appears to be valid. I’ve also been crashing unexpectedly in this same spot for the past few weeks. I assume Jackson is some kind of error assertion that was left in System 7’s Color QuickDraw code. What gives?
___
Jackson was a code name for 32-Bit QuickDraw. The trap you refer to is in fact never called; it’s not supposed to be encountered by you ever. The trap is reserved for Apple to use in future versions of Color QuickDraw. If you examine the code directly preceding the _Debugger, you will notice that it is doing
MOVEQ #$19,D0
JSR ([$1524])
which for you and me is
MoveQ #25,D0 ; say that memory is full…
_SysError ; and call syserror
the line following would be...
_Debugger ; Hey! sysError came back! Better drop into the debugger
What’s all this tell you? You have a debugger installed that is rts’ing from the SysError vector (you aren’t supposed to return from SysError normally), or you have installed your own SysError vector which is rts’ing. At any rate, if you examine the code directly following the debugger statement and see what it does, you might imagine the source code looks something like this:
MemFull MoveQ #25,D0 ; say that memory is full...
_SysError ; and call syserror
; If it returns better go into the debugger since its not supposed to return
_Debugger ; Hey! sysError came back!
;
CallNewHand _NewHandle
bne.S MemFull ; could not get the memory, just die
rts
What’s happening is that you’re running out of memory somehow (several places call MemFull, not just the above place), so you’d need to use a stack crawl to figure out how you got there. But, the bottom line, QuickDraw has run out of memory and cannot continue; it tried to put up a system error dialog to tell the user and for some reason the machine did not get restarted and the SysError vector returned. You are now in your debugger, since QuickDraw put up the system error dialog because it could not continue.
ditherCopy not supported on LaserWriter or ImageWriter
Written: 5/31/91
Last reviewed: 11/6/91
ditherCopy is not supported on LaserWriters or ImageWriters. On a LaserWriter, ditherCopy gets misinterpreted and inverts the image. On an ImageWriter it’s treated as a srcCopy. The ImageWriter driver doesn’t support color grafPorts, which is the only way to do the pixel image required for ditherCopy. Use srcCopy instead for both printers.
Macintosh Color QuickDraw CalcCMask and SeedCFill clarified
Written: 1/1/90
Last reviewed: 11/21/90
I’m having trouble using CalcCMask and SeedCFill. What am I doing wrong?
___
There is some confusion regarding the use of the Macintosh Color QuickDraw routines CalcCMask and SeedCFill, which are analogous to the older CalcMask and SeedFill. Much of the confusion was caused by early documentation errors. Be sure you have the release version of Volume 5 of Inside Macintosh and version 2.0 or later of the MPW interface files.
The correct interface for CalcCMask is:
PROCEDURE CalcCMask(srcBits, dstBits: BitMap;
srcRect, dstRect: Rect;
seedRGB: RGBColor;
matchProc: ProcPtr;
matchData: LongInt);
The correct interface for SeedCFill is:
PROCEDURE SeedCFill(srcBits, dstBits: BitMap;
srcRect, dstRect: Rect;
seedH, seedV: INTEGER;
matchProc: Ptr;
matchData: LongInt);
Each routine calculates a one-bit deep bitmap representing either the mask or the fill area depending upon the routine. In both cases, the source bitmap may be either a bitmap or a pixmap, but the destination must be a bitmap, because it must have a depth of one-bit.
It is difficult to pass a pixmap for the source parameter because of Pascal’s type checking. To get around this difficulty, you can declare a new type:
BitMapPtr = ^BitMap
then use it to coerce the pixmap as follows:
SeedCFill(BitMapPtr(@myPixMap)^, ...);
If you have a PixMapHandle, do the following:
SeedCFill(BitMapPtr(myPixMapHandle^)^, ...);
If you are using a grafPort (or a window), you can pass myWindow^.portBits and not have to worry about whether the port uses a bitmap or a pixmap.
Most of the other parameters are explained in detail in Inside Macintosh. To use the matchProc and the matchData parameters, though, you need more information.
As stated in Inside Macintosh, the matchProc parameter is a pointer to a routine that you would like to use as a custom SearchProc. To better understand how this is used, it is helpful to know how SeedCFill and CalcCMask actually work.
Both routines start by creating a temporary bitmap which, by definition, is one bit deep. The source pixmap (or bitmap) is then copied to the temporary bitmap using CopyBits. This copy causes the image to be converted to a depth of one-bit. Now with a normal black-and-white image, the standard CalcMask or SeedFill routine is used to generate the destination bitmap.
Most of the real work is done in the original call to CopyBits, which maps the pixmap image to a monochrome bitmap equivalent. For each color in the source pixmap, CopyBits will map it to either black or white. Which colors map to black and which ones to white is determined by the SearchProc.
SeedCFill installs a default SearchProc that maps all colors to black except for the color of the pixel at (seedH,seedV). SeedFill then calculates as usual the fill mask for the white bits .
The default SearchProc for CalcCMask maps all colors to white except the color passed in the seedRGB parameter. The seedRGB parameter, then, would be the color of the item that you wanted to “lasso.”
But suppose you want to fill over all colors that were shades of green, not just the particular shade of green at (seedH,seedV). Or maybe you want to fill over all colors that are lighter than 50 percent brightness. Or maybe you want to use dark colors as edge colors for CalcCMask. To do such things, you need to pass a pointer to your own SearchProc in the matchProc parameter.
Because your matchProc is just a custom search procedure for the Color Manager, it should be declared as one, but Volumes I–V of Inside Macintosh have documented this routine incorrectly. The correct declaration for a custom SearchProc is as follows:
FUNCTION SearchProc(VAR RGB: RGBColor;
VAR result: LongInt) : Boolean;
Normally, as each SearchProc is installed, it is added to the head of the SearchProc chain, so that it is called before all of the other ones that were already installed. When a SearchProc is installed, it can do one of three things:
1. Completely ignore the call by returning FALSE and not modifying any of the input parameters;
2. Completely handle the call by setting the result parameter to be the index into the color table that matches (according to your rules) the RGB parameter. In that case, the SearchProc returns TRUE;
3. Partially handle the call by modifying the RGB parameter, then returning FALSE.
In cases 1 and 3, the Color Manager continues down the SearchProc chain until it finds one that returns TRUE. If none of the custom routines handle the call, then the built-in default routine is used. In case 3, you can change the RGB color that is being matched. For example, if you want all shades of green to map to pure green, modify the RGB color, then return FALSE, letting the Color Manager find the index of that green in the color table.
In case 2, you return TRUE to indicate that you handled the call, and you return the color table index in the result parameter. The Color Manager then uses that index. For example, if you want to substitute white for all colors that can’t be matched exactly in the color table, then each time you get called you either return the index into the color table of the exact color, or 0 (which is the index for white) for all other colors.
A custom SearchProc for SeedCFill and CalcCMask should always return TRUE because the default Color Manager SearchProc usually doesn’t make sense. Because SeedCFill and CalcCMask are using CopyBits to copy to a 1-bit bitmap, you need to set the result to be either 0 or 1 (the only possible values in a 1-bit bitmap). A result of 0 is white, and a result of 1 is black.
All colors for SeedCFill that should be “filled over” would generate a result of 0 (white), and all colors that stop the fill generate a 1 (black). SeedFill is then called to fill the white area. All colors for CalcCMask that you want to form boundaries should generate results of 1 (black).
When your SearchProc gets called, the gdRefCon field of the current GDevice (theGDevice^^.gdRefCon) contains a pointer to the following record:
matchRec = RECORD
red: Integer;
green: Integer;
blue: Integer;
matchData: LongInt;
END;
The red, green, and blue parameters for SeedCFill are the values of the color of the pixel at (seedH,seedV). For CalcCMask, they are the fields from the seedRGB parameter. Your SearchProc can use this information to decide which colors are “fill-over” colors and which colors are “boundary” colors. For example, if you always set (seedH,seedV) to be the mouse point, your SearchProc then bases its decisions using the color of the pixel under the cursor. For example, the user clicks a shade of green, so all shades of green get filled over.
The matchData field contains the value that you passed into the SeedCFill or CalcCMask routines in the matchData parameter. The use of this field is completely user-defined. For example, since your SearchProc routine may be a separate module, you might want to use this field to pass a handle to your variables. This field can contain a handle, a pointer, a long integer, or whatever; or you can just ignore this field altogether.
Warning: There are some features of CalcCMask and SeedCFill you should be aware of. To understand them, you should be familiar with the use of CalcMask and SeedFill, which are described in the QuickDraw chapter of Inside Macintosh Volume IV.
CalcCMask and SeedCFill both use a parameter set that is very similar to the one used by CopyBits. CalcMask and SeedFill, however, are a different story. Instead of passing bitmaps and rectangles to SeedFill and CalcMask, these routines use an unusual set of parameters that describe the memory to be operated upon in terms of pointers, height, width, and offsets to the next row (rowBytes). Although these parameters are fairly easy to calculate, there are some limitations.
The most restrictive limitation is that the width of the rectangle used must be an even multiple of 16 bits. This limitation exists because the width of the rectangle is passed to SeedFill and CalcMask as a number of words (2 bytes). When calculating this parameter, SeedCFill and CalcCMask round down to an even word boundary. This rounding means that the rectangles you pass to CalcCMask and SeedCFill should be an even multiple of 16 pixels in width. If they are not, then the rightmost portion of the mask will be garbage.
To figure out the color of the pixel at (seedH,seedV), SeedCFill calls GetCPixel. GetCPixel finds the color of the pixel at (h,v) in the current port. Therefore, if you pass a pixmap that is not the pixmap of the current port you will get bizarre results. In other words, seedH and seedV are expressed in the local coordinates of the current port, not the coordinate of the source pixmap.
You have two methods to make it work. First, always pass the pixmap of the current port as the source parameter. If you are using an off-screen pixmap, it is a good idea to have an associated port for it, and then call SetPort, passing it a pointer your off-screen port, before you call SeedCFill.
The second method involves letting SeedCFill get some wrong value for the color at (seedH,seedV) then using your own custom SearchProc to do the real work. The default SearchProc for SeedCFill relies on getting the correct color, but your SearchProc doesn’t have to.
SeedCFill also makes the assumption that the seedH and seedV parameters are in the local coordinate system of the destination bitmap. This assumption comes into play when SeedCFill calculates the seedH and seedV parameters for SeedFill.
All this means that SeedCFill only works correctly if the source pixmap, destination pixmap, and current port all use the same coordinate system. Because of the above problem, this is almost automatic since the current port’s portRect and the bounds of the source pixmap have to be the same anyway.
The easiest way to make all this work is to have your main port be an even multiple of 16 pixels wide. Then, make sure that your source and destination structures (pixmap or bitmap) are all the same size and all have origins of (0,0).
System 7.0ß1 BitMapToRgn limitation
Written: 1/1/90
Last reviewed: 12/7/90
BitMapToRegion does not work as described in the Macintosh Tech Note “32-Bit QuickDraw: Version 1.2 Features” for a pixmap with baseAddr = (NuBus address). Which calls support pixmap 32-bit base addressing with pmVersion = 4?
___
As of System 7.0ß1, BitMapToRgn cannot handle a bitmap whose base address is in the NuBus address space or any bitmap that requires 32-bit addressing. The problem will be fixed for System 7’s final release. BitMapToRgn seems to be the only call that doesn’t yet support 32-bit addressed bitmaps.
X-Ref:
DTS Macintosh Technical Note “32-Bit QuickDraw: Version 1.2 Features”
Macintosh Color QuickDraw and packed PICTs
Written: 1/1/90
Last reviewed: 12/7/90
Does Macintosh 32-Bit QuickDraw support packed PICTs? What’s the technique for saving packed PICT formats? What compression schemes are supported?
___
Color QuickDraw has always supported packed PICTs. See Inside Macintosh Volume V for details on how CLUT pixmaps are packed. Under 32-Bit QuickDraw, to pack direct RGB pixmaps in PICTs, call CopyBits with the packType field in the source pixmap set to one of the following constants that apply to direct RGB pixmaps:
0—default packing (pixelSize 16 defaults to packType 3 and pixelSize 32 defaults to packType 4)
1—no packing
2—remove pad byte (32-bit pixels only)
3—run-length encoding by pixel size chunks (16-bit pixels only)
4—run-length encoding, all of one component at the time, one scan line at a time (24-bit pixels only)
Scheme 4 will store the alpha channel also if cmpCount is set to to 4. PackSize is not used and should be set to 0 for compatibility reasons. These are the only compression techniques supported at this time.
Macintosh PICT color picture file format
Written: 1/1/90
Last reviewed: 11/21/90
Is there a general file format for color pictures that is common to all of the color paint programs? If so, where is it documented?
___
Apple supports (and encourages developers to support) one file type for pictures: the PICT file type. Most paint-type programs handle PICT files.
A PICT file is composed of two parts in its data fork; the first 512 bytes are for the file header, which contains application-dependent information. You have to contact the individual publishers to find out their particular data structures. For example, you can contact Claris Technical Support at AppleLink CLARIS.TECH or (415) 962-0371 for the file header MacDraw writes to its files.
The rest of the data in the file is picture data as created by Macintosh QuickDraw with OpenPicture. You can find the information about this data in Volume V of Inside Macintosh (pages 84–105); this section also shows how to read/write PICT files.
You can also check the Macintosh Tech Note “Displaying Large PICT Files” for more details on the subject.
X-Refs:
DTS Macintosh Technical Note “QuickDraw’s Internal Picture Definition”
DTS Macintosh Technical Note “Displaying Large PICT Files”
Mac pixmap is clipped to visRgn defined by screenBits.bounds
Written: 1/1/90
Last reviewed: 11/21/90
I’m drawing into a large off-screen bitmap (pixmap), but anything drawn outside the 640- by 480-pixel Macintosh screen area doesn’t get written to the pixmap. Why not?
___
When you create a new port with OpenPort or OpenCPort the visRgn is initialized to the rectangular region defined by screenBits.bounds (IM I:163). If your port has a large portRect, any drawing will be clipped to the visRgn and you will lose any drawing outside of the screenBits.bounds rectangle.
To correct this set the visRgn of the port to coincide with your port’s portRect after creating the port.
Also note that OpenPort initializes the clipRgn to a wide-open rectangular region (-32768, -32768, 32767, 32767). Some operations, like OpenPicture, can fail with this setup, so try setting clipRgn to a smaller rectangle.
X-Refs:
DTS Macintosh Technical Note “Pictures and Clip Regions”
DTS Macintosh Technical Note “Drawing into an Off-Screen Pixel Map”
Using Macintosh System 7 OpenCPicture for higher resolution
Written: 1/1/90
Last reviewed: 12/7/90
We want to use OpenCPicture for higher resolution, not for color per se. Can OpenCPicture in System 7 be used with non-Color as well as Color QuickDraw Macintosh computers?
___
Yes, with System 7, OpenCPicture can be used to create extended PICT2 files from all Macintosh computers. Under System 6.0.7 or later, you must test for 32-Bit QuickDraw before using OpenCPicture. You can do this by calling Gestalt with the gestaltQuickdrawVersion selector. If it returns gestalt32BitQD or greater, then 32-Bit QuickDraw is installed.
How to identify 32-Bit QuickDraw version
Written: 1/1/90
Last reviewed: 11/21/90
How can my program find out which version of Macintosh 32-Bit QuickDraw is running?
___
The following code snippet demonstrates how to use the Gestalt Manager to determine which version of 32-Bit QuickDraw is installed. There is no way to determine the version of 32-Bit QuickDraw before Gestalt. For 32-Bit QuickDraw version 1.2, Gestalt returns 2.2. Inside Macintosh Volume VI describes the Gestalt Manager in detail.
#defineTRUE0xFF
#defineFALSE0
#define Gestalttest0xA1AD
#define NoTrap0xA89F
main()
{
OSErrerr;
longfeature;
if ((GetTrapAddress(Gestalttest) != GetTrapAddress(NoTrap))) {
err = Gestalt(gestaltQuickdrawVersion, &feature);
if (!err) {
if ((feature & 0x0f00) == 0x0000)
printf ("We have Original QuickDraw version 0.%x\n", (feature & 0x00ff));
else if ((feature & 0x0f00) == 0x0100)
printf ("We have 8 Bit QuickDraw version 1.%x\n", (feature & 0x00ff));
else if ((feature & 0x0f00) == 0x0200)
printf ("We have 32 Bit QuickDraw version 2.%x\n", (feature & 0x00ff));
else
printf ("We don't have QD\n");
}
else
printf ("Gestalt err = %i\n",err);
}
else
printf ("No Gestalt\n");
}
Macintosh QDError function under System 6 and System 7
Written: 1/1/90
Last reviewed: 12/7/90
Under what System 7 and System 6 conditions is it legal to call the Macintosh QDError function?
___
Under System 7, QDError can be called from all Macintosh computers. (System 7 supports RGBForeColor, RGBBackColor, GetForeColor, and GetBackColor for all Macintosh computers as well.) On a non-Color QuickDraw Macintosh, QDError always returns a “no error.” Under System 6, QDError cannot be used for non-Color QuickDraw Macintosh systems.
Macintosh CopyBits transfer modes changed for System 7
Written: 1/1/90
Last reviewed: 12/7/90
Why do some Macintosh CopyBits transfer modes produce different results for System 7 than for System 6?
___
Under System 6, the srcOr, srcXor, srcBic, notSrcCopy, notSrcOr, notSrcXor, and notSrcBic transfer modes do not produce the same effect for a 16- or 32-bit (direct) pixel map as for an 8-bit or shallower (indexed) pixel map. With Color QuickDraw these classic transfer modes on direct pixel maps aren’t color-based; they’re pixel-value-based. Color QuickDraw performs logical operations corresponding to the transfer mode on the source and destination pixel values to get the resulting pixel value.
For example, say that a multicolored source is being copied onto a black-and-white destination using the srcOr transfer mode, and both the source and destination are 8 bits per pixel. Except in unusual cases, the pixel value for black on an indexed pixel map has all its bits set, so an 8-bit black pixel has a pixel value of $FF. Similarly, the pixel value for white has all its bits clear, so an 8-bit white pixel has a pixel value of $00. CopyBits takes each pixel value of the source and performs a logical OR with the corresponding pixel value of the destination. Using OR to combine any value with 0 results in the original value, so using OR to combine any pixel value with the pixel value for white results in the original pixel value. Using OR to combine any value with 1 results in 1, so using OR to combine any pixel value with the pixel value for black results in the pixel value for black. The resulting image shows the original image in all areas where the destination image was white and shows black in all areas where the destination image was black.
Take the same example, but this time make the source and destination 32 bits per pixel. The direct-color pixel value for black is $00000000 and the direct-color pixel value for white is $00FFFFFF. CopyBits still performs a logical OR on the source and destination pixel values, but notice what happens in this case. Using OR to combine any source pixel value with the pixel value for white results in white, and using OR to combine any source pixel value with the pixel value for black results in the original color. The resulting image shows the original image in all areas where the destination image was black and shows white in all areas where the destination image was white—roughly the opposite of what you see on an indexed pixel map.
The newer transfer modes addOver, addPin, subOver, subPin, adMax, and adMin work consistently at all pixel depths, and often, though not always, correspond to the theoretical effect of the old transfer modes. For example, the adMin mode works similarly to the srcOr mode on both direct and indexed pixel maps. Also, 1-bit deep source pixel maps work consistently and predictably regardless of the pixel depth of the destination even with the old transfer modes.
Under system software version 7.0, the old transfer modes now perform by calculating with colors rather than pixel values. You’ll find that transfer modes like srcOr and srcBic work much more consistently even on direct pixel maps.
Which QuickDraw versions support SetEntries
Written: 3/3/92
Last reviewed: 6/30/92
I’m calling SetEntries to update the on-screen CLUT. Who implements this call? Does 32-Bit QuickDraw? In other words, does the 32-Bit QuickDraw INIT need to be around for this to work? What about monochrome machines?
I’m creating off-screen buffers by hand instead of using GWorlds. Is this the proper way of doing off-screen buffering when we don’t want to require the user to have 32-Bit QuickDraw?
___
SetEntries is part of the Color Manager, which exists with all Color QuickDraw versions. A good rule of thumb to follow is that if it is documented in Inside Macintosh Volume V, you don’t need 32-Bit QuickDraw to use it. Inside Macintosh Volume V documents standard Color QuickDraw. SetEntries does not work on monochrome Macintosh models, including the Classic II, SE, and PowerBooks.
Off-screen buffering: You should always use GWorlds if they exist; use Gestalt to test for them. This will assure that you can take advantage of the latest speed improvements. It is important to remember that under System 7 NewGWorld and accompanying calls are present in all Macintosh computers including black-and-white systems such as Classic and PowerBook 100 systems.
Macintosh pixel map maximum rowBytes change
Written: 4/22/91
Last reviewed: 6/10/91
The Color QuickDraw section of Inside Macintosh Volume VI states that the restriction on the rowBytes field in a pixmap has been relaxed from $2000 to $4000. When did this happen? Is it true for all 32-Bit QuickDraw versions? This affects our user configuration recommendations.
___
The maximum rowBytes extension to $3FFF or less applies only to 32-bit QuickDraw. Using pixmaps with rowBytes greater than $1FFF when 32-bit QuickDraw is not present is likely to cause problems such as garbage images or system crashes. Remember that 32-bit QuickDraw is always present under System 7.0.
Use assembly to flip a 24-bit off-port color pixmap
Written: 5/7/91
Last reviewed: 7/25/91
What’s the best approach to horizontally flip a 24-bit off-port color pixmap?
___
Unfortunately, you won’t be able to use CopyBits for this kind of procedure; you’ll have to write your own routine to move each pixel. I’d suggest doing this in assembly language to squeeze the best possible performance out of your code.
Construct a 'clut' instead of changing b/w palette entries
Written: 6/10/91
Last reviewed: 8/1/91
How can I change the first and last (white and black) entries in a Macintosh palette?
___
The answer to your question about changing the black and white entries in a palette is a little strange. You can’t simply change the palette associated with an on-screen window, because too many portions of the Toolbox/OS assume that the first entry is white and the last entry is black.
However, what you can do is create an off-screen GWorld and construct a 'clut' for it that does what you want. Creating the 'clut' is fairly straightforward:
Note that using this 'clut' with an off-screen GWorld will work fine except if you attempt to draw text into the GWorld. Apparently drawing text off screen carries the same assumptions that all drawing does on screen.
Once you have done your off-screen drawing with the reversed 'clut' as described above, all that remains is to CopyBits from your off-screen GWorld to your on-screen window. Your on-screen window will need the appropriate palette. Fortunately, constructing that palette from the 'clut' is trivial:
Attaching this palette to the window will cause the correct remapping to occur when you CopyBits from the GWorld to the window, and everything should look just fine.
Why PlotCIcon requires GetCIcon instead of Get1Resource
Written: 4/26/91
Last reviewed: 6/17/91
Why do I have to use GetCIcon(resID) instead of Get1Resource('cicn',resID) forPlotCIcon to work correctly?
___
You apparently thought something that, at first, I thought also: that GetCIcon(resID) is just a utility routine that translates to Get1Resource('cicn',resID). However, this is not the case; GetCIcon not only gets the 'cicn' resource, but it also performs some minor surgery on the results, fills in some placeholder fields in the resource data, and the like. Basically, PlotCIcon can’t work without the things that GetCIcon does.
CopyBits maps source pixmap colors to GDevice inverse table
Written: 4/3/91
Last reviewed: 6/17/91
I’m trying to draw off screen so I made my own CGrafPort, pixmap, and color table, but when I draw into it, the colors come out all wrong. What’s going on here?
___
It’s a very common misconception that CopyBits maps the colors available in the source pixmap’s color table to the colors available in the destination pixmap’s color table.
What actually happens is that CopyBits maps the colors in the source pixmap to the colors available in the current GDevice’s inverse table. See Inside Macintosh Volume V, pages 137 through 139 for a description of inverse tables. Inverse tables is a backwards color table. With a color table, you use a pixel value as an index into the table to return a color. With an inverse table, you use a color-like value as an index into the table to return a pixel value. When CopyBits maps colors from one pixel map to another, it takes a source pixel value, uses the source pixmap’s color table to get the corresponding color, and uses that color as an index into the current GDevice’s inverse table to get the pixel value of the closest color in the destination pixmap’s color table.
Generally speaking, every conceivable color table has exactly one conceivable inverse table. If you alter the contents of a color table, then the inverse table must likewise be altered. It’s just like numbers: for any number you give me, I can give you its negative. For any color table you give me, MakeITable can give you its inverse table. MakeITable is documented in Inside Macintosh Volume V, page 142.
Think of the current GDevice as an implied parameter to CopyBits. If you don’t deal with GDevices at all, then the current GDevice is always the main screen’s GDevice as far as you’re concerned. Color QuickDraw often switches between different screens’ GDevices so that you can draw to multiple screens, but that’s all handled behind your back. If you create a pixmap, give it a color table, and CopyBits to it, then the main screen’s GDevice’s inverse table is used to map colors from the source pixmap. That’s OK as long as your destination pixmap’s color table is compatible with the main screen’s inverse table. If you change the depth and/or color table of the main screen, and then still CopyBits to this same pixmap with the same old depth and color table, then things won’t work correctly because the main screen’s GDevice’s inverse table changes, making it incompatible with your destination pixmap’s color table. This problem usually manifests itself as incorrect colors, but it can result in crashes.
To fix this, you’ll have to remove your reliance on the main screen’s GDevice. To do that you’ll have to make your own GDevice. There’s a routine called NewGDevice, but it always makes the GDevice in the system heap. Instead, you should just call NewHandle to allocate a GDevice record yourself. Here’s what the fields should hold:
gdRefNum—The GDevice has no driver, so set this to 0.
gdID—It doesn’t matter what this is set to—might as well set it to 0.
gdType—Set this to 2 if the off-screen uses direct colors (16 or 32 bits per pixel) or 0 if the off-screen uses a color table (1 through 8 bits per pixel).
gdITable—Allocate a small (maybe just a 2-byte) handle for this field. After you’re done setting up this GDevice and your off-screen pixmap, color table (if any), and CGrafPort, then set this GDevice as the current GDevice by calling SetGDevice. Then call MakeITable, passing it NIL for both the color table and inverse table parameters, and 0 for the preferred inverse table resolution.
gdResPref—I’d guess that more than 99.9 percent of all inverse tables out there have a resolution of 4. Unless you have some reason not to, I’d recommend the same here.
gdSearchProc—Set to NIL. Use AddSearch if you want to use a SearchProc.
gdCompProc—Set to NIL. Use AddComp if you want to use a CompProc.
gdFlags—Set to 0 initially, and then use SetDeviceAttribute after you’ve set up the rest of this GDevice.
gdPMap—Set this to be a handle to your off-screen pixmap.
gdRefCon—Set this to whatever you want.
gdNextGD—Set this to nil.
gdRect—Set this to be equal to your off-screen pixmap’s bounds.
gdMode—Set this to -1. This is intended for GDevices with drivers anyway.
gdCCBytes—Set to 0.
gdCCDepth - Set to 0.
gdCCXData - Set to 0.
gdCCXMask - Set to 0.
gdReserved - Set to 0.
For gdFlags, you should use SetDeviceAttribute to set the noDriver bit and the gDevType bit. You should set the gDevType bit to 1 even if you have a monochrome color table. The 0 setting was only used when monochrome mode was handled by the video driver, and 32-Bit QuickDraw eliminated that convention. Your GDevice doesn’t have a driver anyway.
Once this is done, the GDevice and the off-screen pixmap should be treated as inseparable. When you CopyBits or draws into the pixmap, first call SetGDevice to set its GDevice as the current GDevice. When that’s done, call SetGDevice to restore the previous GDevice. Doing this insulates you from changes in a screen’s GDevice.
If you alter your pixmap’s color table, you should make sure you update the ctSeed of that color table, either by assigning to it the result of GetCTSeed (documented on page 143 of Inside Macintosh Volume V) or by passing a handle to the color table to CTabChanged. The next time that pixmap is drawn into, Color QuickDraw will update your GDevice’s inverse table automatically when it realizes that the ctSeed is different from the current GDevice (which had better be yours) inverse table’s iTabSeed.
GWorlds work this way on Color QuickDraw machines. Every GWorld comes with a pixmap and a GDevice. When you call SetGWorld, that sets both the GWorld and its GDevice as current.
How Macintosh system draws small color icons
Written: 3/31/92
Last reviewed: 5/21/92
The code I added to my application’s MDEF to plot small icons in color works except for when I hold the mouse over an item with color. The color of the small icons is wrong because it’s just doing an InvertRect. When I drag over the Apple menu, the menu inverts behind the icon but the icon is untouched. Is this done by brute force, redrawing the small icon after every InvertRect?
___
As you figured out, the Macintosh system draws color icons, such as the Apple icon on the menu bar, every time the title has to be inverted.
The actual sequence of calls is (more or less) as follows: first InvertRect is called to black the menu title and then PlotIconID is called to draw the icon in its place. The advantage of using PlotIconID is that you don’t have to worry about the depth and size of the icon being used. The system picks the best match from the family whose ID is being passed, taking into consideration the target rectangle and the depth of the device(s) that will contain the icon’s image.
The Icon Utilities call PlotIconID is documented in the Macintosh Technical Note, “Drawing Icons the System 7 Way.” Just in case you don’t have your stack at hand, the interface is:
IconAlignmentType = INTEGER;
IconTransformType = INTEGER;
FUNCTION PlotIconID(theRect: Rect;
align: IconAlignmentType;
transform: IconTransformType;
theResID: INTEGER): OSErr;
INLINE $303C, $0500, $ABC9;
typedef short IconAlignmentType;
typedef short IconTransformType;
pascal OSErr PlotIconID(const Rect *theRect,
IconAlignmentType align,
IconTransformType transform,
short theResID)
= {0x303C, 0x0500, 0xABC9};
Please refer to the Tech Note referenced above for more details on using the calls.
Spooling and preserving Macintosh QuickDraw pixmap depth
Written: 2/11/92
Last reviewed: 9/15/92
When a picture that contains a pixmap is spooled into a window, how and when is the depth of the pixmap in the picture converted to the depth of the screens the window is on?
___
When a picture is spooled in, if QuickDraw encounters any bitmap opcode, it allocates a pixmap of the same depth as the data associated with the bitmap opcode, expands the data into the temporary pixmap, and then calls StdBits. StdBits is what triggers the depth and color conversions as demanded by the color environment (depth, color table, black-and-white settings) of the devices the target port may span (as when a window crosses two or more screens).
If there’s not enough memory in the application heap or in the temporary memory pool, QuickDraw bands the image down to one scan line and calls StdBits for each of these bands. Note that if you’re providing your own bitsProc, QuickDraw will call it instead of StdBits.
This process is the same when the picture is in memory, with the obvious exception that all the picture data is present; the color mapping occurs when StdBits does its stuff.
Determining the resolution of a PICT
Written: 6/10/92
Last reviewed: 9/15/92
In a version 2 picture, the picFrame is the rectangular bounding box of the picture, at 72 dpi. I would like to determine the bounding rectangle at the stored resolution or the resolution itself. Is there a way to do this without reading the raw data of the PICT resource itself?
___
With regular version 2 PICTs (or any pictures), figuring out the real resolution of the PICT is pretty tough. Applications use different techniques to save the information. But if you make a picture with OpenCPicture, the resolution information is stored in the headerOp data, and you can get at this by searching for the headerOp opcode in the picture data (it’s always the second opcode in the picture data, but you still have to search for it in case there are any zero opcodes before it). Or you can use the Picture Utilities Package to extract this information.
With older picture formats, the resolution and original bounds information is sometimes not as obvious or easily derived. In fact, in some applications, the PICT’s resolution and original bounds aren’t stored in the header, but rather in the pixel map structure(s) contained within the PICT.
To examine these pixmaps, you’ll first need to install your own bitsProc, and then manually check the bounds, hRes, and vRes fields of any pixmap being passed. In most cases the hRes and vRes fields will be set to the Fixed value 0x00480000 (72 dpi); however, some applications will set these fields to the PICT’s actual resolution, as shown in the code below.
Inside Macintosh Volume V states that the foreground and background colors are applied to an image during a CopyBits or CopyMask call. Accidental use of this feature can create bizarre coloring effects. This note explains what happens, how to avoid problems, and how to use it.
What Happens
Color QuickDraw has a feature that will allow you to convert a monochrome image to a color image. During a CopyBits or CopyMask call, if the foreground and background colors are not black and white, respectively, Color QuickDraw performs the following operation on every pixel being copied:
NOTE: color table index = pixel value
s = color table index of source pixel
fg = color table index of foreground color
bg = color table index of background color
ColoredPixelValue = (NOT(s) AND bg) OR (s AND fg)
If your source image contains only black and white pixels, then all black pixels would become the foreground color and all white pixels would become the background color. This is because the color table index for white is all zeros and the color table index for black is all ones.
For example, suppose your source image was a 4-bit deep color PixMap. Then the color table index for white (in binary) is 0000 and the index for black is 1111. And let’s suppose that your foreground color is green with an index of 1101 while your background color is red with an index of 0011. Then for the black pixels, the above procedure produces:
ColoredPixelValue = (NOT(1111) AND 0011) OR (1111 AND 1101)
1101 = ( 0000 AND 0011) OR (1111 AND 1101)
And the operation on the white pixels yields:
ColoredPixelValue = (NOT(0000) AND 0011) OR (0000 AND 1101)
0011 = ( 1111 AND 0011) OR (0000 AND 1101)
Possible Problems
This colorizing will only work on 2-color (i.e. black and white) images, and then only if those colors occupy the first and last entries in the color table. Trying to colorize colors that are not the first and last color table entries will yield unexpected results.
This is mainly due to the fact that the colorizing algorithm uses a pixel’s color table index value rather than its actual RGB color. To illustrate this, let’s assume that foreground and background colors are as above, and your image contains yellow with a color table index of 1000. The colorizing operation would give:
ColoredPixelValue = (NOT(1000) AND 0011) OR (1000 AND 1101)
1011 = ( 0111 AND 0011) OR (1000 AND 1101)
Since the color table may have any RGB color at the resulting index position, the final color may not even be close to the source, foreground, or background colors.
Similar things occur if you are trying to colorize a black and white image when white and black do not occupy the first and last positions in the color table.
The bottom line rules for CopyBitsing in a color environment are these:
• Thou shalt set thy background color to white and thy foreground color to black before calling CopyBits or CopyMask, unless thou art coloring a monochrome image.
• Thou shalt, when colorizing, make sure that the first color table entry is white and the last color table entry is black.
The second rule is easy to follow because the default color tables are constructed properly, and if you are using the Palette Manager (and you are, right?) then it will make sure that the color tables obey this rule.
How To Colorize—An Example
This code fragment shows how to implement a color fill, like the paint bucket in MacPaint. It relies on three main things: SeedCFill for calculating the fill area, CopyMask for actually changing the bits, and QuickDraw colorizing.
The variable offBits is an offscreen BitMap (not a PixMap) with bounds = myWindow^.portRect. SeedCFill effectively creates, in the offscreen BitMap, a monochrome image of the bits that we want to paint. Since offBits contains the exact bits that we want to paint, it is used as both the source image and the mask for CopyMask.
By setting the foreground color to the desired paint color, the result is a colorized version of the mask (the paint area) being copied onto the window’s PixMap without affecting any other bits.
Further Reference:
• Color QuickDraw
Deaccelerated _CopyBits & 8•24 GC QuickDraw
Imaging M.IM.GCQDCopybits
Written by: Guillermo A. Ortiz February 1991
This Technical Note discusses conditions that may cause _CopyBits to slow down when QuickDraw acceleration is on via the Apple 8•24 GC Display Card.
Introduction
When a drawing call is issued, GC IPC (Interprocess Communication) takes control of the call and passes it to GC QuickDraw. After the normal port set up (which involves caching the port parameters if this is the first drawing call after the port was set), GC QuickDraw returns control to the application through the IPC and performs, in parallel, the drawing to its own monitor as well as any other monitors that may be affected by the operation. The application then continues its execution, probably issuing more drawing calls that get executed in the same asynchronous manner.
The result of this mode of operation is improved performance, since the application gets control back immediately after issuing the call and the GC QuickDraw moves video data to its own video buffer as well as that of other cards in a more rapid manner by using block transfers and without requiring any action by the main processor.
_CopyBits Conforms To The Same Scheme, Except…
_CopyBits conforms to the same operational scheme, but there are some instances in which GC QuickDraw cannot perform the call in parallel; in this cases it is even possible to suffer a performance loss, since the whole call may have to be completed before control is given back to the application and GC QuickDraw has to make calls and access data across the NuBus™.
The situations that compromise GC QuickDraw parallel operation are as follows:
• When the destination device has a SearchProc installed and the source color environment is different from the destination environment.
QuickDraw calls a SearchProc whenever the source and destination have different depths and when two indexed pixel maps have different color tables, even though their depths may be identical. When GC acceleration is enabled, these conditions cause the following two types of behavior, dependent upon the source pixel map:
• If the source is an indexed pixel map, then GC QuickDraw executes the part of the setup that involves calling the SearchProc, returns control to the main processor, then completes the call in parallel. The act of calling the SearchProc before returning control makes the call slower than when no SearchProc is involved, since parallel operation does not occur throughout the whole call.
• If the source is a direct RGB pixel map, then GC QuickDraw has to call the SearchProc for every pixel that is drawn, and the application does not regain control until after the call to _CopyBits has been completed.
• When the source or destination is offscreen and not created using a GWorld.
GC QuickDraw has no way to detect when an application is going to manipulate a pixel map it has created in memory, so if it has to draw to or copy from such a PixMap, GC QuickDraw has to complete the operation before returning control to the application.
This behavior is contrary to the case when using a GWorld for offscreen environments, since in the case of a GWorld, GC QuickDraw is alerted by the call to _GetPixBaseAddr that the application is getting ready to directly change the pixels. This is the reason why it is so important that applications call _GetPixBaseAddr every time they are about to manipulate a GWorld pixel map directly.
• When the source PixMap has a color table that uses indexes that refer to a palette.
QuickDraw now allows a color table to have indexes that point to entries in the palette associated with the destination window; when bit 14 in the ctFlags field is set, the value fields in the color table are treated as palette entries. When such a PixMap is the source for _CopyBits, then GC QuickDraw has to make a number of calls to the Palette Manager as part of the setup before returning control and completing the call.
This case is similar to that of a indexed pixel map when a SearchProc is involved; therefore, it only implies a partial loss of parallelism; it is good to keep in mind that this case can only occur when the source PixMap is indexed.
Further Reference:
• Inside Macintosh, Volumes V & VI, Color QuickDraw
• d e v e l o p, “Macintosh Display Card 8•24 GC: The Naked Truth,” July 1990.
• Technical Note #275, 32-Bit QuickDraw: Version 1.2 Features
• Developer Notes for the Macintosh Display Cards 4•8, 8•24 and 8•24 GC (APDA, M085TLL/A)
NuBus is a trademark of Texas Instruments.
Drawing Icons
Imaging M.IM.DrawingIcons
Written by: Jim Friedlander October 1985
Using resources of type ICON allows drawing of icons in srcOr mode. Using resources of type ICN# allows for more variety when drawing icons.
There are two different kinds of resources that contain icons: ICON and ICN#. An ICON is a 32 by 32 bit image of an icon and can be drawn using the following Toolbox Utilities calls:
MyIconHndl:= GetIcon(iconID);
PlotIcon(destRect,iconID);
While very convenient, this method only allows the drawing of icons in SrcOr mode (as in the MiniFinder). The Finder uses resources of type ICN# to draw icons on the desktop. Because the Finder uses ICN#s, it can draw icons in a variety of ways.
An ICN# resource is a list of 32 by 32 bit images that are grouped together. Common convention has been to group two 32 by 32 bit images together in each ICN#. The first image is the actual icon, the second image is the mask for the icon. To get a handle to an ICN#, we would use something like this:
TYPE
iListHndl = ^iListPtr;
iListPtr = ^iListStruct;
iListStruct = record
icon : packed array[0..31] of Longint;
mask : packed array[0..31] of Longint;
End; {iListStruct}
VAR
myILHndl : iListHndl; {handle to an ICN#}
iBitMap : BitMap; {BitMap for the icon}
mBitMap : BitMap; {BitMap for the mask}
MyILHndl:= iListHndl(GetResource('ICN#',iconID));
if MyILHndl = NIL then HandleError;
{and exit or whatever is appropriate}
Once we have a handle to the icons, we need to set up two bitMaps that we will be using later in CopyBits:
SetRect(icnRect,0,0,32,32); { define the icon's 'bounds'}
With iBitMap do Begin
baseAddr:= @MyILHndl^^.icon;
rowbytes:= 4; { 4 * 8 =32}
bounds:= icnRect;
End; {with}
With mBitMap do Begin
baseAddr:= @MyILHndl^^.mask;
rowbytes:= 4;
bounds:= icnRect;
End; {with}
Icons can represent desktop objects that are either selected or not. Folder and volume icons can either be open or not. The object (or the volume it is on) can either be online or offline. The Finder draws icons using all permutations of open, selected and online:
Drawing icons as non-open is basically the same for online and offline volumes. We need to punch a hole in the desktop for the icon. This is analogous to punching a hole in dough with an irregular shaped cookie-cutter. We can then sprinkle jimmies* all over the cookie and they will only stick in the area that we punched out (the mask). We do this by copyBitsing the mask onto the desktop (whatever pattern) to our destRect. For non-open, non-selected icons:
we use the SrcBic mode so that we punch a white hole:
we need to do a little more work. We need to XOR a ltGray pattern into the boundsRect of the icon. We will then punch the hole, draw the icon and then XOR out the ltgray pattern that does not fall inside the mask. So, to draw the icon as offline, non-open, non-selected we would:
GetPenState(OldPen); {save the pen state so we can restore it}
PenMode(patXor);
PenPat(ltGray);
PaintRect(destRect); {paint a ltGray background for icon}
Drawing the opened icons requires one less step. We don’’t have to CopyBits the icon in, we just use the mask. Online and offline icons are drawn the same way. To draw icons as open, selected:
we do the following:
GetPenState(OldPen); {save the pen state so we can restore it}
PenMode(patXor);
PenPat(dkGray); { the icon is selected, so we need dkGray }
PaintRect(destRect); { paint a dkGray background for icon}
PaintRect(destRect); {XOR out bits outside of the mask, leaving
the mask filled with dkGray}
SetPenState(OldPen); {restore the old pen state}
To draw icons as open, non-selected:
we just need to change one line from above. Instead of XORing with a dkGray pattern, we use a ltGray pattern:
PenPat(ltGray); {icon is non-selected, so we need ltGray}
These techniques will work on any background, window-white or desktop-gray and all patterns in between. Have fun.
* jimmies : little bits of chocolate
Further Reference:
• QuickDraw
• Toolbox Utilities
Drawing Icons the System 7 Way
Imaging M.IM.IconDrawing
Revised by: Don Moccia and C.K. Haun <TR> October 1992
Written by: Jim Mensch and David Collins October 1991
This Technical Note describes how to utilize the built-in System 7 icon drawing utility. Use this information to better conform to the System 7 visual human interface.
Changes since May 1992: In this Note, we replaced the C and Pascal interface files and corrected the related text. So much text was tweaked that change bars are used only on code changes.
Introduction
With the introduction of System 7 for the Macintosh, Apple has defined a new look and feel for many screen elements that better utilize color. Among those redefined elements are the icons drawn by the Finder and other system components. Until now, Apple has not documented how to draw icons the way the Finder does in System 7.
This Technical Note discusses the icon toolkit calls that the Finder uses to draw and manipulate the screen icons. Two of the calls, PlotIconID and PlotCIconHandle, are the ones you will probably use the most since they simply deal with drawing single icons to the screen. Some parts of the toolbox require that an icon family handle be passed to them to allow the drawing of color icons. The icon toolkit provides calls that allow you to create, draw, and manipulate these handles.
The New 'ic' Type Resources
PlotIconID and PlotCIconHandle allow the use of standard CIcons as documented in Inside Macintosh Volume V. The PlotIconID call also permits the use of a new set of icon resources documented in Inside Macintosh Volume VI, Chapter 9. This new set is a collection of different icons, representing a single Finder object, into a family. Each member of the family has the same resource ID as the 'ICN#', and a resource type indicating the icon data it contains. Currently Apple has defined three sizes of icons and three bit depths for each size. The sizes are large (32 by 32 pixels), small (16 by 16 pixels), and mini (12 by 12 pixels). The bit depths are 1, 4, and 8. The actual resource types are defined as:
Large1BitMask = 'ICN#';
Large4BitData = 'icl4';
Large8BitData = 'icl8';
Small1BitMask = 'ics#';
Small4BitData = 'ics4';
Small8BitData = 'ics8';
Mini1BitMask = 'icm#';
Mini4BitData = 'icm4';
Mini8BitData = 'icm8';
The 1-bit-per-pixel member of each size also contains the mask data for all icons of that size (yes, this means that all your icons of a certain size must have the same mask). A 1-bit-per-pixel member must exist for each icon size that PlotIconID uses. The icon size used is determined by the size of the destination rectangle. If the destination rectangle is greater than 16 pixels on a side then the large icon will be used. If the rectangle is 13–16 pixels on both sides, the small icon will be used. If it is 12 or less on each side, the mini-icon will be used. The bit depth is determined by the device of the grafPort you plot into at drawing time. Be sure to create a color grafPort when you want to use color icons.
Icon Families (or Suites and Caches As the Tool Set Refers to Them)
An icon family is simply a collection of icon handles that contain up to one image of each bit depth and size for a given icon. The family can be fully populated (every possible size or depth available), or it can have only those icons that exist or are needed. By using families, you remove the need to determine which size or depth of icon to use when drawing into a given rectangle. Several system routines, the Notification Manager for example, can take an icon family handle when an icon is requested. This permits them to use the proper color icons if available. In the case of a sparsely populated icon family, when the proper icon is not available, the icon toolkit will pick a substitute to produce the best results.
An icon cache is a family that also has a ProcPtr and a refCon. The main difference between a cache and a family is that the elements of the cache’s array are sparsely populated. When using an icon cache, the system either will use the entry in the icon family portion of the cache or, if the desired element is empty, it will call the procedure pointed to by the ProcPtr and request the data for the icon. The procedure should have this interface:
FUNCTION IconGetter(theType: ResType;
yourDataPtr: Ptr): Handle;
This function should return either the icon data to be drawn or NIL to signify that this entry in the icon cache does not exist. Icon caches can be used with all icon family calls. A few extra calls are also available to manipulate icon caches.
Drawing Modes or Transforms
In addition to various sizes and bit depths, icons can be drawn with different modes or transforms. Transforms are analogous to certain Finder states for the icons. For example, the transform that you would use to show an icon of a disk that has been ejected is ttOffline. Here is a list of the available transforms:
ttNone = $0;
ttDisabled = $1;
ttOffline = $2;
ttOpen = $3;
ttSelected = $4000;
ttSelectedDisabled = (ttSelected + ttDisabled);
ttSelectedOffline = (ttSelected + ttOffline);
ttSelectedOpen = (ttSelected + ttOpen);
The actual appearance of the icon drawn by each transform type may vary with future system software, so you should always use the transform that best fits the state it represents in your application. This way you will be consistent with future changes to the look and feel of regular system icons. Note the ttSelected transform can be added to any of the other transform types.
There are also transforms that use the Finder label colors to color the icon. To determine the proper label for a file’s icon, you can check bits 1–3 of the fdFlags field in the file’s Finder info. (See the Finder Interface chapter in Inside Macintosh Volume VI for more information). These bits contain a number from 0 to 7. Simply add the corresponding ttLabel value to the transform that you give the call. The label values are defined like this:
ttLabel1 = $0100;
ttLabel2 = $0200;
ttLabel3 = $0300;
ttLabel4 = $0400;
ttLabel5 = $0500;
ttLabel6 = $0600;
ttLabel7 = $0700;
Alignment
Most icons do not fully fill their rectangle, and it is sometimes necessary to draw an icon relative to other data (like menu text). In these instances it is nice to be able to have the icon move in its rectangle so that it will be at a predictable location in the destination rectangle. When drawing an icon you can pass one of these standard alignments in the alignment parameter or you can add a vertical alignment to a horizontal alignment to create a composite alignment value.
And Now (Drum Roll Please) the Calls and What to Pass
Now that we have defined every major data type we can think of, here are the actual toolkit calls themselves. One word of caution: only the ForEachIconDo call protects the handle that is passed to it, so make your icon resources nonpurgeable.
Icon Family Calls
FUNCTION NewIconSuite(VAR theIconSuite: Handle): OSErr;
NewIconSuite returns an empty icon family handle with all members set to NIL.
FUNCTION AddIconToSuite(theIconData: Handle;
theSuite: Handle;
theType: ResType): OSErr;
This call will add the data in theIconData into the suite at the location reserved for theType of icon data. AddIconToSuite will replace any old data in that slot without disposing of it, so you may want to call GetIconFromSuite to obtain the old handle (if any) to dispose of it. This call will be used most often with the NewIconSuite call to fill the empty family after it’s created.
FUNCTION GetIconFromSuite(VAR theIconData: Handle;
theSuite: Handle;
theType: ResType): OSErr;
This call will return a handle to the pixel data of the family member of theSuite specified by theType. If you intend to dispose of this handle, be sure to call AddIconToSuite with a NIL handle to zero out the family entry.
FUNCTION ForEachIconDo(theSuite: Handle;
selector: IconSelectorValue;
action: IconAction;
yourDataPtr: Ptr): OSErr;
This routine will call your IconAction procedure (see below) for each icon in the family specified by selector and theSuite. The selector parameter is a bit-level flag that specifies which family members to operate on; they can be added together to create composite selectors that work on several different family members. The values for selector are:
The action procedure that gets called for each icon type selected for the family is a Pascal type function with the following interface:
FUNCTION IconAction(theType: ResType;
VAR theIcon: Handle;
yourDataPtr: Ptr): OSErr;
The parameter theIcon is passed by reference here so that your routine can modify the contents of the suite directly. The yourDataPtr parameter is the value passed when you called ForEachIconDo. It allows you to easily communicate with your application. The action procedure returns an OSErr. If any value other than noErr is returned, ForEachIconDo will stop processing immediately and return the error passed. (Note: This implies that the icons selected may only be partially operated on. There is no guaranteed order in which the icons get operated on.)
FUNCTION GetIconSuite(VAR theIconSuite: Handle;
theResID: INTEGER;
selector: IconSelectorValue): OSErr;
GetIconSuite will create a new icon family and fill it from the current resource chain with the icons of resource ID theResID and types indicated by selector. This is the call you will probably use most often to create an icon family. Note that if you SetResLoad(False) before making this call, the suite will be filled with unloaded resource handles.
FUNCTION PlotIconSuite(theRect: Rect;
align: IconAlignmentType;
transform: IconTransformType;
theIconSuite: Handle): OSErr;
This call renders the proper icon image from the passed icon family based on the bit depth of
the display you are using and the rectangle that you have passed. The parameters align and transform are applied to the icon selected for drawing and then the icon is plotted into the current grafPort. PlotIconSuite chooses the appropriate icon based primarily on size. Once the proper icon size is determined (based on the destination rectangle), the present member of that size with the deepest bit depth that the current device can use is selected. A size category is considered present if the black-and-white member (with mask), 'ICN#', 'ics#', or 'icm#', is present. PlotIconSuite can be used for both picture accumulation and printing.
FUNCTION DisposeIconSuite(theIconSuite: Handle;
disposeData: BOOLEAN): OSErr;
This call disposes the icon family handle itself. In addition, if disposeData is true, any of the icon data handles that do not belong to a resource fork will also be disposed.
FUNCTION SetSuiteLabel(theSuite: Handle; theLabel: INTEGER): OSErr;
This call allows you to specify a label to draw an icon of this suite when no label is specified in PlotIconSuite. This is used primarily to ensure that a family passed to a system routine gets drawn with the proper label. The default label can be overridden by specifying a label in PlotIconSuite.
FUNCTION GetSuiteLabel(theSuite: Handle): INTEGER;
GetSuiteLabel returns the label previously set with SetSuiteLabel.
Icon Cache Calls
In addition to the icon family calls, icon caches have these additional calls:
FUNCTION MakeIconCache(VAR theHandle: Handle;
makeIcon: IconGetter;
yourDataPtr: UNIV Ptr): OSErr;
This call creates an empty icon cache similar to NewIconSuite, and associates the additional icon loading procedure and data value with the family.
FUNCTION LoadIconCache(theRect: Rect;
align: IconAlignmentType;
transform: IconTransformType;
theIconCache: Handle): OSErr;
This call allows preflight loading of certain elements of your icon cache. This is handy if you suspect that certain drawing operations may occur at a time not convenient for loading your icon data (e.g., when your resource fork might not be in open chain). LoadIconCache takes the same parameters as PlotIconSuite and uses the same criteria to select the icon to load. The grafPort must be set properly before making this call since it is one of the criteria for determining the icon to load.
The following four calls are provided to change theData or theProc associated with an icon cache:
FUNCTION GetIconCacheData(theCache: Handle;
VAR theData: Ptr): OSErr;
FUNCTION SetIconCacheData(theCache: Handle;
theData: Ptr): OSErr;
FUNCTION GetIconCacheProc(theCache: Handle;
VAR theProc: IconGetter): OSErr;
FUNCTION SetIconCacheProc(theCache: Handle;
theProc: IconGetter): OSErr;
Plotting Icons Not Part of a Suite
The next calls are grouped because they are similar. They let you plot an icon to the screen without your creating an icon suite. They are also good if you have a 'cicn' instead of an icon family.
FUNCTION PlotIconID(theRect: Rect;
align: IconAlignmentType;
transform: IconTransformType;
theResID: INTEGER): OSErr;
FUNCTION PlotCIconHandle(theRect: Rect;
align: IconAlignmentType;
transform: IconTransformType;
theCIcon: CIconHandle): OSErr;
FUNCTION PlotIconMethod(theRect: Rect;
align: IconAlignmentType;
transform: IconTransformType;
theMethod: IconGetter;
yourDataPtr: UNIV Ptr): OSErr;
FUNCTION PlotIconHandle(theRect: Rect;
align: IconAlignmentType;
transform: IconTransformType;
theIcon: Handle): OSErr;
FUNCTION PlotSICNHandle(theRect: Rect;
align: IconAlignmentType;
transform: IconTransformType;
theSICN: Handle): OSErr;
All these routines share the following parameters: theRect is the destination rectangle to draw the indicated icon into; align is the alignment method to use if the icon does not fit the rectangle given; transform indicates the desired appearance of the icon on the screen.
In PlotIconID, the parameter theResID is the resource ID of the family of 'ic' type resources to use. If the correct bit depth or the size required is not defined, the closest-fitting one will be used.
The PlotCIconHandle parameter theCIcon is a handle that you get to a standard QuickDraw color icon. Unlike PlotCIcon, PlotCIconHandle does not honor the current foreground and background colors. Call GetCIcon to load the icon. Dispose of it when you are done, since they can take up quite a bit of memory.
PlotIconMethod calls your IconGetter procedure, discussed earlier, to check for the existence of icon data.
PlotIconHandle will plot the data from an 'ICN#' or 'ICON' resource from its handle. It is a new version of PlotIcon.
PlotSICNHandle plots the data of a 'SICN' resource from its handle. Only 'SICN' resources with a single member, or one in which the second member is a mask for the first, will plot correctly.
All the functions return an error code if things did not go well with the drawing or, in the case of the PlotIconID call, if the indicated icon family could not be used.
Miscellaneous Calls
FUNCTION GetLabel(labelNumber: INTEGER;
VAR labelColor: RGBColor;
VAR labelString: Str255): OSErr;
This call returns the actual color and string used in the label menu of the Finder and the label’s Control Panel. This information is provided in case you wish to include the label text or color when displaying a file’s icon in your application.
FUNCTION IconSuiteToRgn(theRgn: RgnHandle;
iconRect: Rect;
align: IconAlignmentType;
theIconSuite: Handle): OSErr;
FUNCTION IconIDToRgn(theRgn: RgnHandle;
iconRect: Rect;
align: IconAlignmentType;
iconID: INTEGER): OSErr;
FUNCTION IconMethodToRgn(theRgn: RgnHandle;
iconRect: Rect;
align: IconAlignmentType;
theMethod: IconGetter;
yourDataPtr: Ptr): OSErr;
These routines will create a region from the mask of the icon selected by the iconRect and align values passed. They will allow you to do accurate hit testing and outline dragging of an icon in your application. The RgnHandle must have been previously allocated before you make this call.
FUNCTION RectInIconSuite(testRect: Rect;
iconRect: Rect;
align: IconAlignmentType;
theIconSuite: Handle): BOOLEAN;
FUNCTION RectInIconID(testRect: Rect;
iconRect: Rect;
align: IconAlignmentType;
iconID: INTEGER): BOOLEAN;
FUNCTION RectInIconMethod(testRect: Rect;
iconRect: Rect;
align: IconAlignmentType;
theMethod: IconGetter;
yourDataPtr: Ptr): BOOLEAN;
FUNCTION PtInIconSuite(testPt: Point;
iconRect: Rect;
align: IconAlignmentType;
theIconSuite: Handle): BOOLEAN;
FUNCTION PtInIconID(testPt: Point;
iconRect: Rect;
align: IconAlignmentType;
iconID: INTEGER): BOOLEAN;
FUNCTION PtInIconMethod(testPt: Point;
iconRect: Rect;
align: IconAlignmentType;
theMethod: IconGetter;
yourDataPtr: Ptr): BOOLEAN;
These calls hit test the passed Point or Rect against the icon indicated. The parameters iconRect and align, and the grafPort should be the same as when the icon was last drawn. The functions return true if the point is in the icon mask or if the rectangle intersects the icon mask.
Error Codes
The Icon Utilities will pass back any errors encountered during execution, so you can expect to see Memory Manager, Resource Manager, and other normal errors.
There is one error code defined specifically for the Icon Utilities routines that may be returned by the Icon plotting routines.
{ Pascal }
CONST
noMaskFound = -1000;
END;
/* C */
#define noMaskFound -1000
This error will be returned if the Icon Utilities package could not find or create a mask for the icon family. The Icon Utilities will use the correct mask for each icon size, if one is available. If no mask for a specific size is available, a mask will be created from any mask in the family, but if there are no 1 bit images and no mask in the family, plotting calls will fail with this error.
Type(def)s and Glue for Pascal and C
The Pascal and C interfaces are provided here to copy and paste since the current MPW standard interface files do not contain the glue for these calls. Electronic versions of this note are on AppleLink (Developer Support: Developer Services: Technical Documentation: Macintosh Technical Notes: Imaging: Graphics: Icon Drawing in 7.sit (Stuffit)) and the Developer CD (Technical Documentation: Macintosh Technical Notes: Imaging: Graphics: Icon Drawing in 7).
MPW C, Pascal, and Assembler files also have been submitted to AppleLink and the Developer CD, but their paths were not known when this note was written.
• Inside Macintosh, Volume VI, Finder Interface chapter
Displaying Large PICT Files
Imaging M.IM.LargePict
Revised by: March 1988
Written by: Rick Blair July 1987
Now that we have scanners and other massive-picture producing types of applications, there is a need to address the problem of how to display a PICT format object that is bigger than a current PICT resource is allowed to be. Note that this technique applies equally well to version 1 and version 2 (word-opcode) pictures as produced by the Macintosh II.
Future Compatibility
Think of the handle returned by a GetResource('PICT',ID) as a “handle” in the more general sense of being an abstract “tag”—something that the ROM routines can use to draw the picture with. Don’t assume that the entire picture has been read into memory or that you can directly read any bytes beyond the basic Picture record structure (picSize followed by picFrame). Someday we may provide a mechanism for the resource to be disk- instead of memory-based. The QuickDraw bottleneck procedures will know how to get data from and put data into the pictures in any case.
Spooling from a PICT file
In order to display pictures of arbitrary size, your application should be able to import a QuickDraw picture from a file of type PICT. This is the file produced by a “Save as…” from MacDraw with the PICT option selected.
What follows is a small program fragment that demonstrates how to spool in a picture from [the data fork of] a PICT file. The picture can be larger than the historical 32K resource size. See technical note #88 if you are unfamiliar with the Signal mechanism. We assume that a CatchSignals has been done before GetandDrawPICTFile is called.
MPW Pascal Example
{the following variable must be at the top level}
VAR
globalRef : INTEGER; {refNum of the file to read from}
{the following procedure must be at the top level}
DrawPicture(myPicture,&(**myPicture).picFrame); /*draw the picture*/
err = GetFPos(globalRef,&filePos);/*get position for check*/
if (err != noErr) return err;
err = FSClose(globalRef);
if (err != noErr) return err;
DisposHandle((Handle)myPicture);
(*qd.thePort).grafProcs = savedProcs;/*restore the procs*/
/*Check for errors. if there wasn't enough room,*/
/*DrawPicture will abort; the FILE position mark*/
/*won't be at the end of the FILE.*/
if (filePos != myEOF) return abortPICT;
else return noErr;
} /*if (reply.good) */
} /* GetDrawPICTFile */
More on Picture Compatibility
Many applications already support PICT resources larger than 32K. The 128K ROMs (and later) allow pictures as large as memory (or spooling) will accommodate. This was made possible by having QuickDraw ignore the size word and simply read the picture until the end-of-picture opcode was reached.
For maximum safety and convenience, let QuickDraw generate and interpret your pictures.
While Apple has provided you with the data formats that allow you to read or write picture data directly, we recommend that you always let DrawPicture or OpenPicture and ClosePicture process the opcodes.
One reason to read a picture directly by scanning the opcodes would be to disassemble it to, for example, extract a Color QuickDraw pixel map to save off in a private data structure. This shouldn’t normally be necessary.
If you do look at the picture data be sure and check the version information. You may want to put up an alert in your application that indicates to the user when a picture was created using a later version of the picture format than your application recognizes, letting them know that some elements of the picture cannot be displayed. If the version information indicates a QuickDraw picture version later than the one recognized by your application, your program should skip over the new opcodes and only attempt to parse the ones it knows.
As with reading picture data directly, it is best to use QuickDraw to create data in the PICT format. If you do need to create PICT format data directly, it is essential that you use the latest opcode specifications and that you thoroughly test the data produced on both color and black and white Macintosh machines. Contact Macintosh Developer Technical Support if you are not sure that you have the latest specifications.
Apple does not guarantee that a picture which wasn’t produced by QuickDraw will work.
Further Reference:
• QuickDraw
• Technical Note M.IM.PictureOpcodes —
Internal Picture Format
• Technical Note M.PT.Signals —
Signals
LaserWriter Utility Q&As
Imaging M.IM.LWUtil.Q&As
Revised by: Developer Support Center October 1992
Written by: Developer Support Center October 1990
This Technical Note contains a collection of Q&As relating to a specific topic—questions you’ve sent the Developer Support Center (DSC) along with answers from the DSC engineers. While DSC engineers have checked the Q&A content for accuracy, the Q&A Technical Notes don’t have the editing and organization of other Technical Notes. The Q&A function is to get new technical information and updates to you quickly, saving the polish for when the information migrates into reference manuals.
Q&As are now included with Technical Notes to make access to technical updates easier for you. If you have comments or suggestions about Q&A content or distribution, please let us know by sending an AppleLink to DEVFEEDBACK. Apple Partners may send technical questions about Q&A content to DEVSUPPORT for resolution.
New Q&As and Q&As revised this month are marked with a bar in the side margin.
SCSI drive format for LaserWriter II NTX with Rev. 3 ROMs
Written: 5/3/91
Last reviewed: 6/26/91
What could be causing intermittent PostScript errors from a LaserWriter II NTX with an SCSI hard disk mounted after installing the Rev 3 ROM upgrade?
___
The LaserWriter II NTX with Rev 3 ROMs does not work properly with a hard disk formatted with the LaserWriter Font Utility 1.x. You need to reformat the disk and copy the fonts back onto the hard disk using the LaserWriter Font Utility 2.0.2. Unfortunately, there is no way to make this procedure easier.
LaserWriter Font Utility copies Postscript file to printer
Written: 9/23/91
Last reviewed: 10/8/91
Is there a utility that will send a PostScript file from disk to the LaserWriter?
___
The LaserWriter Font Utility handles this job and is part of the System 7 disk set. On the System 7 Golden Master CD, the path is System 7.0: System Software 7.0: Installer Version: Tidbits folder.
Drawing Into an Off-Screen Bitmap
Imaging M.IM.OffscreenBitMap
Revised by: Jon Zap & Forrest Tanaka June 1990
Written by: Jim Friedlander & Ginger Jernigan July 1985
This Technical Note provides an example of creating an off-screen bitmap, drawing to it, and then copying from it to the screen.
Changes since April 1990: Clarified the section on window updates with off-screen bitmaps to explicitly limit these updates to your own windows.
The following is an example of creating and drawing to an off-screen bitmap, then copying from it to an on-screen window. We supply this example in both MPW Pascal and C.
MPW Pascal
First, let’s look at a general purpose function to create an off-screen bitmap. This function creates the GrafPort on the heap. You could also create it on the stack and pass the uninitialized structure to a function similar to this one.
FUNCTION CreateOffscreenBitMap(VAR newOffscreen:GrafPtr; inBounds:Rect) : BOOLEAN;
VAR
savePort : GrafPtr;
newPort : GrafPtr;
BEGIN
GetPort(savePort); {need this to restore thePort after OpenPort changes it}
newPort := GrafPtr(NewPtr(sizeof(GrafPort))); {allocate the GrafPort}
IF MemError <> noErr THEN BEGIN
CreateOffscreenBitMap := false; {failed to allocate it}
EXIT(CreateOffscreenBitMap);
END;
{
the OpenPort call does the following . . .
allocates space for visRgn (set to screenBits.bounds) and clipRgn (set wide open)
sets portBits to screenBits
sets portRect to screenBits.bounds
etc. (see IM I-163,164)
side effect: does a SetPort(offScreen)
}
OpenPort(newPort);
{make bitmap exactly the size of the bounds that caller supplied}
WITH newPort^ DO BEGIN {portRect, clipRgn, and visRgn are in newPort}
portRect := inBounds;
RectRgn(clipRgn, inBounds); {avoid wide-open clipRgn, to be safe}
RectRgn(visRgn, inBounds); {in case inBounds is > screen bounds}
END;
WITH newPort^.portBits DO BEGIN {baseAddr, rowBytes and bounds are in newPort}
bounds := inBounds;
{rowBytes is size of row It must be rounded up to even number of bytes}
ClosePort(oldOffscreen); { dump the visRgn and clipRgn }
DisposPtr(oldOffscreen^.portBits.baseAddr); { dump the bits }
DisposPtr(Ptr(oldOffscreen)); { dump the port }
END;
Now that you know how to create and destroy an off-screen bitmap, let’s go through the motions of using one. First, let’s define a few things to make the _NewWindow call a little clearer.
CONST
kIsVisible = true;
kNoGoAway = false;
kMakeFrontWindow = -1;
myString = 'The EYE'; {string to display}
Here’s the body of the test code:
VAR
offscreen : GrafPtr; {our off-screen bitmap}
ovalRect : Rect; {used for example drawing}
myWBounds : Rect; {for creating window}
OSRect : Rect; {portRect and bounds for off-screen bitmap}
myWindow : WindowPtr;
BEGIN
InitToolbox; {exercise left to the reader}
myWBounds := screenBits.bounds; { size of main screen }
InsetRect(myWBounds, 50,50); { make it fit better }
DestroyOffscreenBitMap(offscreen); {remove the evidence}
WHILE NOT Button DO; {give user a chance to see the results}
END.
MPW C
First, let’s look at a general purpose function to create an off-screen bitmap. This function creates the GrafPort on the heap. You could also create it on the stack and pass the uninitialized structure to a function similar to this one.
Boolean CreateOffscreenBitMap(GrafPtr *newOffscreen, Rect *inBounds)
{
GrafPtr savePort;
GrafPtr newPort;
GetPort(&savePort); /* need this to restore thePort after OpenPort */
newPort = (GrafPtr) NewPtr(sizeof(GrafPort)); /* allocate the grafPort */
if (MemError() != noErr)
return false; /* failed to allocate the off-screen port */
/*
the call to OpenPort does the following . . .
allocates space for visRgn (set to screenBits.bounds) and clipRgn (set wide open)
sets portBits to screenBits
sets portRect to screenBits.bounds
etc. (see IM I-163,164)
side effect: does a SetPort(&offScreen)
*/
OpenPort(newPort);
/* make bitmap the size of the bounds that caller supplied */
newPort->portRect = *inBounds;
newPort->portBits.bounds = *inBounds;
RectRgn(newPort->clipRgn, inBounds); /* avoid wide-open clipRgn, to be safe */
RectRgn(newPort->visRgn, inBounds); /* in case newBounds is > screen bounds */
/* rowBytes is size of row, it must be rounded up to an even number of bytes */
if (MemError()!=noErr) { /* check to see if we had enough room for the bits */
SetPort(savePort);
ClosePort(newPort); /* dump the visRgn and clipRgn */
DisposPtr((Ptr)newPort); /* dump the GrafPort */
return false; /* tell caller we failed */
}
/* since the bits are just memory, let's clear them before we start */
EraseRect(inBounds); /* OpenPort did a SetPort(newPort) so we are ok */
*newOffscreen = newPort;
SetPort(savePort);
return true; /* tell caller we succeeded! */
}
Here is the function to get rid of an off-screen bitmap created by the previous function:
void DestroyOffscreenBitMap(GrafPtr oldOffscreen)
{
ClosePort(oldOffscreen); /* dump the visRgn and clipRgn */
DisposPtr(oldOffscreen->portBits.baseAddr); /* dump the bits */
DisposPtr((Ptr)oldOffscreen); /* dump the port */
}
Now that you know how to create and destroy an off-screen bitmap, let’s go through the motions of using one. First, let’s define a few things to make the _NewWindow call a little clearer.
#define kIsVisible true
#define kNoGoAway false
#define kNoWindowStorage 0L
#define kFrontWindow ((WindowPtr) -1L)
Here’s the body of the test code:
main()
{
char* myString = "\pThe EYE"; /* string to display */
GrafPtr offscreen; /* our off-screen bitmap */
Rect ovalRect; /* used for example drawing */
Rect myWBounds; /* for creating window */
Rect OSRect; /* portRect and bounds for off-screen bitmap*/
WindowPtr myWindow;
InitToolbox(); /* exercise for the reader */
myWBounds = qd.screenBits.bounds; /* size of main screen */
InsetRect(&myWBounds, 50,50); /* make it fit better */
DestroyOffscreenBitMap(offscreen); /* dump the off-screen bitmap */
while (!Button()); /* give user a chance to see our work of art */
}
Comments
In the example code, the bits of the BitMap structure, which are pointed to by the baseAddr field, are allocated by a _NewPtr call. If your off-screen bitmap is close to the size of the screen, then the amount of memory needed for the bits can be quite large (on the order of 20K for the Macintosh SE or 128K for a large screen). This is quite a lot of memory to lock down in your heap and it can easily lead to fragmentation if you intend to keep the off-screen bitmap around for any length of time. One alternative that lessens this problem is to get the bits via _NewHandle so the Memory Manager can move them when necessary. To implement this approach, you need to keep the handle separate from the GrafPort (for example, in a structure that combines a GrafPort and a Handle). When you want to use the off-screen bitmap you would then lock the handle and put the dereferenced handle into the baseAddr field. When you are not using the off-screen bitmap you can then unlock it.
This example does not demonstrate one of the more typical uses of off-screen bitmaps, which is to preserve the contents of windows so that after a temporary window or dialog box obscures part of your windows and is then dismissed, you can quickly handle the resulting update events without recreating all of the intermediate drawing commands.
Make sure you only restore the pixels within the content regions of your own windows in case the temporary window partly obscures windows belonging to other applications or to the desktop. Another application could change the contents of its windows while they are behind your temporary window, so you cannot simply restore all the pixels that were behind the temporary window because that would restore the old contents of the other application’s windows. Instead, you could keep keep an off-screen bitmap for each of your windows and then restore them by copying each bit map into the corresponding window’s ports when they get their update events.
An alternate method is to make a single off-screen bitmap that is as large as the temporary window and a region that is the union of the content regions of your windows. Before you display the temporary window, copy the screen into the off-screen bit map using the region as a mask. After the temporary window is dismissed, restore the obscured area by copying from the off-screen bit map into a copy of the Window Manager port, and use the region as a mask. If the region has the proper shape and location, it prevents _CopyBits from drawing outside of the content regions of your windows. See Technical Note #194, WMgrPortability for details about drawing across windows.
In some cases it can be just as fast and convenient to simply define a picture (PICT) and then draw it into your window when necessary. There are cases, however, such as text rotation, where it is advantageous to do the drawing off the screen, manipulate the bit image, and then copy the result to the visible window (thus avoiding the dangers inherent in writing directly to the screen). In addition, this technique reduces flicker, because all of the drawing done off the screen appears on the screen at once.
It is also important to realize that, if you plan on using the pre-Color QuickDraw eight-color model, an off-screen bitmap loses any color information and you do not see your colors on a system that is capable of displaying them. In this case you should either use a PICT to save the drawing information or check for the presence of Color QuickDraw and, when it is present, use a PixMap instead of a BitMap and the color toolbox calls (Inside Macintosh, Volume V) instead of the standard QuickDraw calls (Inside Macintosh, Volume I).
You may also want to refer to the OffScreen library (DTS Sample Code #15) which provides both high- and low-level off-screen bitmap support for the 128K and later ROMs. The OffSample application (DTS Sample Code #16) demonstrates the use of this library.
Further Reference:
• Inside Macintosh, Volumes I & IV, QuickDraw
• Inside Macintosh, Volume V, Color QuickDraw
• Technical Note M.IM.PrincipiaOffscreen —
Principia Off-Screen Graphics Environments
• Technical Note M.TB.WMgrPort —
WMgrPortability
• DTS Macintosh Sample Code #15, OffScreen & #16, OffSample
Old Style Colors
Imaging M.IM.OldColors
Revised by: Rich “I See Colors” Collyer August 1990
Written by: Rich “I See Colors” Collyer & Byron Han October 1989
This Technical Note covers limitations of the original Macintosh color model (eight-color) which Inside Macintosh, Volume I-173, QuickDraw does not document.
Changes since October 1989: Added definitions of the old-style constants.
QuickDraw has always been able to deal with color, just on a very limited basis. Most applications have not made use of this feature, since Color QuickDraw-based Macintoshes come with a better color model. There are, however, a few nice features which come with the old style color model. With the old style colors, it is easy to print color on an ImageWriter with a color ribbon. Another advantage is that developers do not have to write special-case code depending upon whether or not a machine has Color QuickDraw.
Now that you are ready to convert to the old style colors, there are a few things you should know about which do not work with old style colors. This Note covers the limitations of using old style colors, as well as the best ways to work around these limitations.
Limitations
The most obvious limitation is that of only eight colors: black, white, red, green, blue, cyan, yellow, and magenta. This limitation is only a problem if you want to produce a color-intensive application; if this describes your application, then you need not read any further in this Note.
The next limitation is that off-screen buffers are not very useful. You can draw into off-screen buffers, but there is no way to get the colors back from the buffer. This leads into the next limitation, which is that _CopyBits cannot copy more than one color at a time.
When you call _CopyBits from an off-screen buffer to your window, you need to set the forecolor to the color you want to copy before calling _CopyBits (i.e., to copy a red object, call _ForeColor(redColor)). Now when you copy the object, you can only copy one color. If you copy different colored objects at one time, then you have a problem. The result of a multicolored copy is that all objects copy in the same color, that of the foreground.
It is possible to work with an off-screen buffer and the old style colors, but it requires a lot of extra work. Unless the objects are really complex, then it is probably easier to just draw the objects directly into your window.
One other limitation does exist. Consider the following code sample. One would assume that this sample would work at all times.
SetPort (myPort);
savedFG := myPort^.fgColor;
ForeColor (redColor); {or any other color}
{...drawing takes place here...}
ForeColor (savedFG);
Surprise. It does not always work. The saved value for the fgColor field of the GrafPort is not a classic QuickDraw color if the GrafPort is actually a CGrafPort. If dealing with a CGrafPort, the fgColor field actually contains the foreground color’s entry in the color table, so the second call to _ForeColor really messes things up.
The proper way to set and reset the foreground color with classic QuickDraw’s _ForeColor call is as follows:
SetPort (myPort);
savedFG := myPort^.fgColor;
ForeColor (redColor); {or any other color}
{...drawing takes place here...}
myPort^.fgColor := savedFG; {manually stuff the old fgColor back}
If (32BQD = TRUE) Then {32BQD is a flag which is made and set by}
PortChanged (myPort); {the application; to set it, the application}
{needs to check _Gestalt for 32-Bit QuickDraw}
This Note also applies to the routine _BackColor.
What Works
The easiest way to work with these limited colors is to use pictures. When you draw the images, you should draw into a picture. Then when you want to draw the images into your window or to a printer, call _DrawPicture. Pictures work well with the old style colors, and you don’t need to worry about making sure that the forecolor is current when you draw into your window.
Once you have the picture, you can use it to draw into the screen or to the printer port. You can also set the WindowRecords windowPic to equal your PictureHandle so updates are handled by the Window Manager.
What Do Those Constants Mean Anyway
Each of the constants contains nine bits of information, and each bit has a special meaning. Figure 1 illustrates the meaning of each of the bits, while Table 1 shows how each of the color constants fills in the appropriate bits.
Figure 1–Bit Definitions
black white red green blue cyan magenta yellow
(33) (30) (209) (329) (389) (269) (149) (89)
Cyan 0 0 0 1 1 1 0 0
Magenta 0 0 1 0 1 0 1 0
Yellow 0 0 1 1 0 0 0 1
Black 1 0 0 0 0 0 0 0
Red 0 1 1 0 0 0 1 1
Green 0 1 0 1 0 1 0 1
Blue 0 1 0 0 1 1 1 0
Inverse 0 1 0 0 0 0 0 0
Normal 1 0 1 1 1 1 1 1
Table 1–Color-Bit Correlation
Further Reference:
• Inside Macintosh, Volume I-173, QuickDraw
• Technical Note M.IM.Copybits —
Of Time and Space and _CopyBits
Things You Wanted to Know About _PackBits*
*But Were Afraid to Ask
Imaging M.IM.PackBits
Revised by: Guillermo Ortiz, Jon Zap, and Forrest Tanaka January 1992
Written by: Cameron Birse November 1987
This Technical Note describes the format of data packed by the Toolbox utility _PackBits and documents a change to the srcBytes limit and possible worst case. Although you can simply unpack this data using _UnPackBits, Apple provides this information for the terminally curious and for those manipulating MacPaint® documents or PICT files by hand.
Warning: This format information is subject to change.
Changes since November 1990: A warning has been added about the handling of a flag-counter byte value of -128.
Length Doesn’t Matter
Inside Macintosh, Volume I-470, describes the Pascal interface to the _PackBits trap as follows:
The accompanying text states that srcBytes, the length of your uncompressed data, should not be greater than 127, and that in the worst case, the compressed data can be srcBytes + 1. To pack more than 127 bytes, you had to break the data up into 127-byte groups and call _PackBits on each group. Beginning with system software version 6.0.2, this limit of 127 bytes is no longer valid. The new limit is 32,767 bytes, which is the maximum positive number that srcBytes can hold. The worst case can be determined according to the following formula:
(srcBytes + (srcBytes+126) DIV 127)
which is comparable to what you would get if you broke up the data into 127-byte groups and picked up an additional byte for each group.
Mommy, How Do They Make Packed Bits?
The first byte is a flag-counter byte that specifies whether or not the the following data is packed, and the number of bytes involved. If this first byte is a negative number, then the following data is packed. In this case, the number is the two’s complement of a zero-based count of the number of times the data byte repeats when expanded. There is one data byte following this first byte in packed data. The byte after the data byte is the next flag-counter byte.
If the flag-counter byte is a positive number, then the following data is unpacked. In this case, the number is a zero-based count of the number of incompressible data bytes that follow. There are (flag-counter+1) data bytes following the flag-counter byte. The byte after the last data byte is the next flag-counter byte.
Note that there is no way to know, given a pointer to the start of packed data, when you have reached the end of the packed data. This is why you need to know either the length of the packed or unpacked data before you start unpacking. _UnPackBits requires the length of the unpacked data.
Warning: _PackBits never generates the value -128 ($80) as a flag-counter byte, but a few PackBits-like routines that are built into some applications do. _UnpackBits handles this situation by skipping any flag-counter byte with this value and interpreting the next byte as the next flag-counter byte. If you’re writing your own UnpackBits-like routine, make sure it handles this situation in the same way.
Consider the following example:
Unpacked data:
AA AA AA 80 00 2A AA AA AA AA 80 00 2A 22 AA AA AA AA AA AA AA AA AA AA
After being packed by _PackBits:
FE AA ; (-(-2)+1) = 3 bytes of the pattern $AA
02 80 00 2A ; (2)+1 = 3 bytes of discrete data
FD AA ; (-(-3)+1) = 4 bytes of the pattern $AA
03 80 00 2A 22 ; (3)+1 = 4 bytes of discrete data
F7 AA ; (-(-9)+1) = 10 bytes of the pattern $AA
or
FE AA 02 80 00 2A FD AA 03 80 00 2A 22 F7 AA
* * * * *
The bytes with the asterisk (*) under them are the flag-counter bytes. _PackBits packs the data only when there are three or more consecutive bytes with the same data; otherwise it just copies the data byte for byte (and adds the count byte).
Note: The data associated with some PICT opcodes, $0098 (PackBitsRect) and $0099 (PackBitsRgn), contain PixData which is basically made of _PackBits data. It should be noted, though, that the format for PixData includes a byteCount or length in addition to the data described in this Note.
For example, the following is the result of decoding a sample PICT2:
/* Now we have the scan line data packed as follows:
[bytecount for current scan line] [data as defined above]
If rowBytes is > 250 then byteCount is a word else is a byte
(in this case, byteCount is a byte)
note that each unpacked row adds to 30 rowBytes
*/
/* line 1, byte count is 2 (best case for a row) */
02
E3 FF /* -(-29) + 1 = 30 FF's */
/* line 2, byte count is 19 (0x13) */
13
01 FF 23 /* 1+1 data bytes */
FE 00 /* -(-2)+1 0's */
FC 23 /* -(-4)+1 0x23's */
FE 00 /* 3 0's */
FC 23 /* 5 0x23's */
FE 00 /* 3 0's */
FC 23 /* 5 0x23's */
FE 00 /* 3 0's */
00 FF /* 1 data byte */
/* line 3, byte count is 28 */
1C
02 FF 00 23 /* 3 data bytes */
FE 00 /* 3 0's */
FE 23 /* 3 0x23's */
01 00 23 /* 2 data bytes */
FE 00 /* 3 0's */
FE 23 /* 3 0x23's */
01 00 23 /* 2 data bytes */
FE 00 /* 3 0's */
FE 23 /* 3 0x23's */
04 00 23 00 00 FF /* 5 data bytes */
/* line 4, byte count is 31 (worst case for a row) */
1F
03 FF 00 00 23 /* 4 data bytes */
FE 00 /* 3 0's */
00 23 /* 1 data byte */
FE 00 /* 3 0's */
00 23 /* 1 data byte */
FE 00 /* 3 0's */
00 23 /* 1 data byte */
FE 00 /* 3 0's */
00 23 /* 1 data byte */
FE 00 /* 3 0's */
00 23 /* 1 data byte */
FE 00 /* 3 0's */
02 23 00 FF /* 3 data bytes */
/* line 5, byte count is 28 */
1C
01 FF 00 /* 2 data bytes */
FE 23 /* 3 0x23's */
01 00 23 /* 2 data bytes */
FE 00 /* 3 0's */
FE 23 /* 3 0x23's */
01 00 23 /* 2 data bytes */
FE 00 /* 3 0's */
FE 23 /* 3 0x23's */
01 00 23 /* 2 data bytes */
FE 00 /* 3 0's */
FE 23 /* 3 0x23's */
00 FF /* 1 data byte */
/* line 6, byte count is 18 */
12
00 FF /* 1 data byte */
FC 23 /* 5 0x23's */
FE 00 /* 3 0's */
FC 23 /* 5 0x23's */
FE 00 /* 3 0's */
FC 23 /* 5 0x23's */
FE 00 /* 3 0's */
FD 23 /* 4 0x23's */
00 FF /* 1 data byte */
/* line 7, byte count is 2 (best case for a row) */
02
E3 FF /* 30 0xFF's */
00 /* pad so next command starts at word boundary */
00FF /*end of pic */
};
Further Reference:
• Inside Macintosh, Volume I-465, The Toolbox Utilities
• Inside Macintosh, Volume V-39, Color QuickDraw
• Technical Note M.PT.MacPaintDoc —
MacPaint Document Format
MacPaint is a registered trademark of Claris Corporation.
Palette Manager Changes in System 6.0.2
Imaging M.IM.PaletteManagerChanges
Written by: Guillermo Ortiz October 1988
This Technical Note describes the changes and enhancements to the Palette Manager in System Software 6.0.2 and future versions.
Application Palette
Applications now have the ability to define a default palette for the system to use when it needs to define the color environment (i.e., when it creates a color window without an associated palette or displays a dialog box).
The application palette feature is especially cool in cases where a color application uses old-style dialogs and alerts because without an application palette, the system will use the default palette to define the color environment. Since the system uses the default palette, the color environment may change (will change in 16-color mode) to cause some “cosmic” colors to appear in the active window. Defining a default application palette with two colors, black and white, solves this problem.
If the system needs a palette to define a color environment, it looks in the resource fork of the application for the 'pltt' ID = 0 resource and uses the palette which it contains. If the system cannot find this resource in the application’s resource fork, it will use its own default palette (resource 'pltt' ID = 0 in the System file) if present, or, if necessary, it will use the Palette Manager’s built-in palette.
Once an application has set its color environment (by calling _InitMenus, or _InitPalettes in weird instances when there are no menus) it can find the default palette by calling GetPalette ( WindowPtr (-1) ) or change the default palette by calling SetPalette ( WindowPtr (-1), newDefPltt, true ). Note that the initialization of the Palette Manager with a call to _InitMenus is contrary to the way Inside Macintosh, Volume V, The Palette Manager documents it.
One Palette, Many Ports
You can now associate one palette with many CGrafPort and CWindow records, thus simplifying the use of a single palette with multiple ports and windows; System Software 6.0 and earlier require copies of the palette to use it with different windows.
Although this ability to associate one palette with multiple ports and windows will allow the use of calls like _PmForeColor and _PmBackColor, calling _ActivatePalette with an off-screen port does nothing, and as a result, calling it with an off-screen port will associate the palette with the port but will not cause any change in the color environment.
One important implication of this feature is that DisposeWindow (_DisposWindow) will not dispose of the associated palette automatically since it may be allocated to other ports or windows. The only exception to this behavior is when an application has used _GetNewCWindow to create the window, there is a 'pltt' resource with the same ID as the window, and the application has not called _GetPalette for the window.
Color Updates
System version 6.0.2 also introduces a new call, _NSetPalette, which complements _SetPalette. _NSetPalette has the same functionality as _SetPalette, but the CUpdates parameter has been modified from a Boolean to an Integer as follows:
_NSetPalette changes the palette associated with dstWindow to srcPalette. It also records whether the window wants to receive updates as a result of a change to its color environment. If you want dstWindow to be updated whenever its color environment changes, set nCUpdates to pmAllUpdates. If you are only interested in updates when dstWindow is the active window, set nCUpdates to pmFgUpdates. If you are only interested in updates when dstWindow is not the active window, set nCUpdates to pmBkUpdates.
_CopyPalette is a utility procedure that copies dstLength entries from the source palette into the destination palette; the copy begins at srcEntry and dstEntry, respectively. _CopyPalette will resize the destination palette when the number of entries after the copy is greater than the original.
_CopyPalette does not call _ActivatePalette, so the application is free to do a number of palette changes without causing a series of intermediate changes to the color environment; the application should call _ActivatePalette after completing all palette changes.
If either of the palette handles are NIL, _CopyPalette does nothing.
Palette Manager Q&As
Imaging M.IM.PaletteMgr.Q&As
Revised by: Developer Support Center October 1992
Written by: Developer Support Center October 1990
This Technical Note contains a collection of Q&As relating to a specific topic—questions you’ve sent the Developer Support Center (DSC) along with answers from the DSC engineers. While DSC engineers have checked the Q&A content for accuracy, the Q&A Technical Notes don’t have the editing and organization of other Technical Notes. The Q&A function is to get new technical information and updates to you quickly, saving the polish for when the information migrates into reference manuals.
Q&As are now included with Technical Notes to make access to technical updates easier for you. If you have comments or suggestions about Q&A content or distribution, please let us know by sending an AppleLink to DEVFEEDBACK. Apple Partners may send technical questions about Q&A content to DEVSUPPORT for resolution.
New Q&As and Q&As revised this month are marked with a bar in the side margin.
Macintosh Palette Manager and offscreen graphics
Written: 7/22/91
Last reviewed: 8/1/92
The Macintosh Palette Manager doesn’t work on offscreen environments the way you’d expect. Unlike color windows, SetPalette will not change the offscreen’s color table; rather it just allows you to use PMForeColor and PMBackColor to set the current drawing color in that environment. To change the offscreen’s color table you’ll need to convert the palette to a color table and then set the resulting color table to the off screen. Calling Palette2CTab will do the converting for you.
To get around having to use palettes to define the current drawing color in the off screen, you can always use Index2Color and then RGBForeColor to get the color to be set for drawing. A remake of GiMeDaPalette code sample, available on the latest Developer CD Series disc, does offscreen drawing in place of having to continually copy a PICT.
RestoreDeviceClut and color flash when application quits
Written: 8/23/91
Last reviewed: 8/1/92
When my application, which uses a color palette, quits, there is momentary but distracting flash of weird colors in the Finder windows and the desktop temporarily appears in a weird color. Is there any way to get around this?
___
When you quit, RestoreDeviceClut is called to restore the color table and an update event is called to redraw the screen. It’s the delay between the change in the color table and the update event that causes the flash of incorrect colors to be displayed. This, unfortunately, is unavoidable.
Restoring Finder desktop colors after using Palette Manager
Written: 8/28/91
Last reviewed: 8/1/92
After using the Macintosh Palette Manager, how do I restore the Finder’s desktop colors?
___
The Finder desktop’s colors are restored automatically on quitting applications that use the Palette Manager. Colors aren’t restored automatically when switching from your application to another, but if that application needs a certain set of colors and uses the Palette Manager to get them, then it’ll have them the moment it comes to the front. If you’re concerned about applications that don’t use the Palette Manager, you can use RestoreDeviceClut(gd:GDHandle), passing the handle to the GDevice of the screen you want to reset, or nil if you want to reset all of your devices. Passing nil to RestoreDeviceClut is your best bet, as it is very straightforward, and resets all of your monitors. You may not wish to do this, however, because RestoreDeviceClut is only available on machines with 32-bit color QuickDraw.
To reset a screen’s GDevice for machines without 32-bit color QuickDraw, you will need to keep track of the color table.When your application starts up, get the GDevice’s color table and save it—you’ll need it later. This value can be found at (**(**GDHandle).gdPMap).pmTable, where gdPMap is a PixMapHandle, and pmTable is a CTabHandle which tells you the absolute colors for this image. These data structures are found in Inside Macintosh Volume V, pages 52 and 119.
Build your application’s “world” using the Palette Manager, and avoid low-level methods of changing colors. When your application is about to quit and you want to restore the environment to its original state, get the color table you saved in the beginning. Convert this to a palette using CTab2Palette. Then set your window to this palette with SetPalette. This will cause the environment to update to the original color table that you initially got from the GDevice. If the application that is behind your application is Palette Manager friendly, then it will restore the environment to its palette. You may also want to do this procedure at the suspend event, as shown in the DTS sample MacApp program, FracApp. One of the problems that you won’t be able to solve this way involves multiple monitors. You won’t know which one to update. Only the monitor that has the window that you’ve called ActivatePalette on will update.
If your application changes the color environment with the Palette Manager, then RestoreDeviceClut is called automatically when your application quits. This means that you shouldn’t have to worry about restoring the palette if you don’t want to. There is a catch, however (there always is). When you use the SADE version of MultiFinder (6.1b9), it prevents this from automatically happening. Other versions of MultiFinder don’t have this side effect.
SetPalette cUpdates, NSetPalette, and window update events
Written: 9/26/91
Last reviewed: 8/1/92
When I pass false in the cUpdates parameter to SetPalette, I still get update events to that window when I modify its palette. What’s going on?
___
SetPalette’s cUpdates parameter controls whether color-table changes cause that window to get update events only if that window is NOT frontmost. If that window is frontmost, then any changes to its palette causes it to get an update event regardless of what the cUpdates parameter is. When you call SetEntryColor and then ActivatePalette for your front-most window, it gets an update event because it’s the front-most window even though you passed false in the cUpdates parameter. Another important point is that windows that don’t have palettes also get update events even when another window’s palette is activated.
Fortunately, system software version 6.0.2 introduced the NSetPalette routine, which you can find documented in the Macintosh Technical Note “Palette Manager Changes in System 6.0.2,” and on page 20-20 in the revamped Palette Manager chapter of Inside Macintosh Volume VI. This variation of SetPalette gives you a lot more flexibility in controlling whether your window gets an update event than SetPalette does. If you pass pmAllUpdates in the nCUpdates parameter, then that window gets an update event when either it or another window’s palette is activated. If you pass pmFgUpdates, then it gets an update event when a palette is activated only if it’s the front-most window (in effect, it only gets an update event if its own palette is activated). If you pass pmBkUpdates, then it gets an update event when a palette is activated only if it’s not the front-most window (in effect, it only gets an update event if another window’s palette is activated). If you pass pmNoUpdates, then that window never gets an update event from any window’s palette being activated, including that window itself.
Picture Comments—The Real Deal
Imaging M.IM.PictComments
Revised by: Joseph Maurer October 1992
Written by: Ginger Jernigan November 1986
Changes since March 1988: This Note (formerly titled “Optimizing for the LaserWriter—PicComments”) describes the picture comments defined and interpreted by the Apple printer drivers. Most of the picture comments are specific to PostScript, but we renamed the Note to emphasize that LaserWriter printers are not necessarily PostScript devices, and that QuickDraw printer drivers may implement their own picture comment handling. This Note has been completely rewritten and incorporates all additional insights gained during the last few years. We are also much more determined now to discourage the use of obsolete and problem-laden (although still supported) picture comments, and we carefully point out known problems or limitations of each comment.
Introduction
The QDProcs record (see Inside Macintosh Volume I, page 197) reflects the foundations of the architecture of QuickDraw. The commentProc field points to a procedure that processes picture comments, as included in a picture by means of the PicComment procedure (Inside Macintosh Volume I, page 189). This allows applications to include application-specific additional information in the pictures they create.
The QDProcs record also is the key to understanding how Macintosh printer drivers work. When the application calls PrOpenPage and draws into the printing grafPort, the printer driver collects the drawing commands by hooking into the QDProcs of the printing port. In particular, if an application calls the PicComment procedure while drawing into the printing grafPort, the printer driver gets a chance to capture and process the information contained in the kind and dataHandle parameters.
During the development of the original LaserWriter driver, it became obvious that applications should be able to take advantage of certain PostScript features that were not accessible through standard QuickDraw calls, such as rotated text and graphics, dashed lines, fractional line widths, and smoothed polygons. Also, certain applications needed a way to transmit their own native PostScript instructions to the printer. Picture comments seemed to be the ideal vehicle for providing these capabilities.
Unfortunately, there are conflicts with the device-independent nature of the Macintosh Printing Manager architecture. In this Note, we still want to document picture comments as completely and correctly as possible; and we want to tell you how to use the best of their features, while maintaining the important goal of device-independent printing and all- purpose PICTs. (This is why it has such a painful history!)
First, we give an overview of the picture comments as currently implemented by Apple’s printer drivers. This leads us immediately to the problem section “Cohabitation of QuickDraw and PostScript,” which also shows how to keep the QuickDraw and PostScript graphics states synchronized during printing. Finally, we discuss all the picture comments by subject, in the order suggested by Table 1.
Picture Comments Repertoire
The following picture comments are recognized by all PostScript LaserWriter drivers version 3.1 and later.
Table 1-PostScript LaserWriter Picture Comments
Type Kind Data Size Data Description
TextBegin 150 6 TTxtPicRec Begin text function
TextEnd 151 0 NIL End text function
StringBegin 152 0 NIL Begin string delimitation
StringEnd 153 0 NIL End string delimitation TextCenter 154 8 TTxtCenter Offset to center of rotation
LineLayoutOff 155 0 NIL Turn LaserWriter line layout off
LineLayoutOn 156 0 NIL Turn LaserWriter line layout on
# ClientLineLayout 157 16 TClientLL Customize line layout error
distribution
PolyBegin 160 0 NIL Begin special polygon
PolyEnd 161 0 NIL End special polygon
PolyIgnore 163 0 NIL Ignore following polygon data
PolySmooth 164 1 PolyVerb Close, Fill, Frame
PolyClose 165 0 NIL Close the polygon
DashedLine 180 - TDashedLine Draw following lines as dashed
DashedStop 181 0 NIL End dashed lines
SetLineWidth 182 4 Point Set fractional line widths
PostScriptBegin 190 0 NIL Set driver state to PostScript
PostScriptEnd 191 0 NIL Restore QuickDraw state
PostScriptHandle 192 - PSData PostScript data in handle
† PostScriptFile 193 - FileName FileName in data handle
† TextIsPostScript 194 0 NIL QuickDraw text is sent as PostScript
† ResourcePS 195 8 Type/ID/Index PostScript data in a resource file
PSBeginNoSave 196 0 NIL Set driver state to PostScript
RotateCenter 202 8 Center Offset to center of rotation
# FormsPrinting 210 0 NIL Don’t clear print buffer after each page
# EndFormsPrinting 211 0 NIL End forms printing after PrClosePage
_______________________________
† These comments are obsolete.
# These comments are not recommended.
Most of the comments in Table 1 were designed specifically for the original LaserWriter driver. In fact, the term LaserWriter has been (and often still is) used in the sense of “PostScript printer,” and the LaserWriter driver is known to be basically a QuickDraw-to-PostScript translator. Meanwhile, however, QuickDraw-based LaserWriter models came out, so we should start being more careful in our terminology. This is why we insist on talking about PostScript drivers or PostScript printers when a picture comment applies to PostScript.
QuickDraw printer drivers may implement their own picture comments, or some of the above comments, in order to provide additional capabilities. Certain third-party printer drivers implement text rotation, for example, by supporting the TextBegin/TextCenter/ TextEnd picture comments.
Apple’s QuickDraw printer driver for the LaserWriter SC supports the following three picture comments:
LineLayoutOff 155 0 NIL Turn LaserWriter line layout off
LineLayoutOn 156 0 NIL Turn LaserWriter line layout on
SetLineWidth 182 4 Point Set fractional line widths.
The ImageWriter LQ driver and the first versions of the StyleWriter driver (prior to 7.2) implement the LineLayoutOff and LineLayoutOn picture comments. Even the ImageWriter driver reacts to picture comments:
BitMapThinningOff 1000 0 NIL Turn off hi-res bitmap thinning
BitMapThinningOn 1001 0 NIL Turn on hi-res bitmap thinning
The ImageWriter driver does the same toggling of the “bitmap thinning” of fat bitmaps in Best mode, when it encounters a TextBegin or TextEnd comment (undocumented feature—never mind!). The ImageWriter LQ driver handles these comments similarly.
The current StyleWriter driver (version 7.2.2) and the personal LaserWriter LS driver do not support any picture comments at all.
The point of all this is:
It is impossible to determine which picture comments
are supported by which printer driver.
In other words, your application should never assume a particular picture comment is available, but your application also should not defeat the device-independent design of the Macintosh printing architecture by writing printer driver–specific code!
Of course, you know (Inside Macintosh Volume II, page 152) that the high byte of the prStl .wDev field of the print record identifies a printer driver species, and that a value of $03 tells you the printer driver belongs to the PostScript LaserWriter driver ancestry. As a matter of fact, many applications use this information to achieve special printing features not available through the Printing Manager interface.
And, of course, you also know that we don’t like this idea. One reason is future system software may allow spool files to be redirected to a printer other than the one chosen when you sent your printing instructions (including picture comments). Another reason is that picture comments usually are included in PICTs; documents containing such pictures should print with optimal results on any printer configuration. And, finally, you never know what the future holds for you, in terms of new printing devices or new printer drivers—or a new printing architecture!
Instead, if a picture (i.e., a sequence of imaging instructions) contains picture comments to enhance the output on devices that support them, it should also contain a standard QuickDraw representation as a fallback solution, in case the rendering device does not recognize the picture comments. The design and implementation of these picture comments should incorporate conventions to make this cohabitation of two representations in one picture possible.
Cohabitation of QuickDraw and PostScript
Device-Independent Pictures
We can think of the Printing Manager’s PrOpenPage and PrClosePage calls as being analogous to the OpenPicture and ClosePicture calls (which, by the way, reminds us to never call OpenPicture between PrOpenPage and PrClosePage; see Inside Macintosh Volume II, page 160). In both cases, a stream of imaging instructions is recorded for deferred rendering. We want to create pictures that include both QuickDraw and optimized PostScript representations so that we obtain the best results in all circumstances. We must take special care for third-party QuickDraw printer drivers that support picture comments originally intended for PostScript devices only.
Let’s start with the easy ones.
The two picture comments PostScriptBegin and PostScriptEnd clearly suggest that any imaging instructions in between are intended exclusively for PostScript printing devices. In the case of the PostScript LaserWriter driver, the effect of PostScriptBegin is to disable all bottlenecks except commentProc, txMeasProc, getPicProc, and putPicProc. This means that QuickDraw’s text, line, shape (Rects, RoundRects, Ovals, Arcs, Polygons) and bitmap drawing calls don’t have any effect in the printing grafPort when enclosed by PostScriptBegin and PostScriptEnd. Instead, the PostScript LaserWriter driver expects to receive the imaging instructions as data enclosed in the PostScriptHandle comment. This way, both the PostScript and QuickDraw representation can coexist in the same picture without conflict. As a consequence, non-PostScript printer drivers, unable to interpret general PostScript text, must not imitate this behavior of ignoring QuickDraw instructions, even when they implement other picture comments such as TextBegin and TextEnd for text rotation. Otherwise, they would miss the QuickDraw representation of some PostScript imaging.
The text rotation picture comments (TextBegin, TextCenter, TextEnd) silently include the assumption that a printer driver that supports these comments
a. ignores the QuickDraw clipping region between TextBegin and TextEnd
b. ignores the QuickDraw CopyBits instruction within TextBegin/TextEnd
This way, a bitmap representation of the rotated text can be included in the picture. It will be used only if the TextBegin/TextEnd comments are not supported. Conversely, the QuickDraw commands required to draw the text to be rotated by the printer driver are “hidden” from QuickDraw by setting the clipping region to empty, which is ignored by the driver supporting the comments.
The polygon picture comments provide another solution to the problem, in form of the special comment PolyIgnore. It allows one to include a QuickDraw representation of the smoothed polygon, ignored by a driver that supports polygon smoothing (such as via PostScript’s curve operator). And for filled polygons, QuickDraw’s region concept works around a conflict of who owns which polygon (see sample code later in this Note).
Some picture comments (such as the line layout comments) do not require a fallback solution in case they are not supported by a printer driver; or the feature, if absent, is not a big loss (such as SetLineWidth, provided you use it only for widths smaller than one 72-dot-per-inch (dpi) QuickDraw pixel).
But for the picture comments DashedLine/DashedStop and RotateBegin/ RotateCenter/RotateEnd, there is no general solution to the “cohabitation” problem; and we are distressed about it. It is obvious that they have been defined with the PostScript LaserWriter driver in mind, without anticipating a future furnished by some 150 third-party printer drivers. The only way to include both representations in these cases is indeed to assume that only PostScript drivers will support the picture comment, such that the PostScriptBegin and PostScriptEnd comments can be used to “comment out” the QuickDraw representation.
Even under the above assumption, we still need a trick to prevent the QuickDraw calls within the scope of the picture comments from showing up when the comments are not recognized. Fortunately, early Macintosh developers discovered a QuickDraw feature that, unintentionally, solves the problem. Passing the “magic” mode 23 to PenMode inhibits QuickDraw’s normal drawing, but still lets the LaserWriter driver see the drawing instructions come through the bottlenecks, so that it can translate them into PostScript. Note that this pen mode always has been undocumented, and that using it was considered a compatibility risk and frowned upon for some time. Given the current state of affairs, however, there is no reason anymore to be paranoid about it.
Keeping QuickDraw and PostScript Synchronized
There are two situations, in the context of picture comments, where the design of the PostScript LaserWriter driver requires special precautions from the application programmer.
First, certain QuickDraw instructions like Move, MoveTo, PenPat, and PenSize change the state of the grafPort, without going through the QDProcs bottleneck procedures. A Macin-tosh printer driver takes these changes into account only at the time it executes an actual drawing instruction. Remember, the printer driver hooks into the QDProcs to get execution time and only “sees” instructions coming through the QDProcs. Nothing is wrong with it—unless PostScript code is woven into the graphics instructions by means of picture comments. (Note that PostScript code may be generated transparently when the LaserWriter driver encounters certain picture comments.) If the PostScript code assumes that the current state of the grafPort corresponds to what you expect it to be, then you have to flush the state of the grafPort explicitly before inserting the PostScript code. This is easier than it sounds; just do something inoffensive that goes through the QDProcs.lineProc bottleneck, like in the following utility procedure:
PROCEDURE FlushGrafPortState;
{ This routine causes the state of the Printing Manager's grafPort to be }
{ flushed out to the LaserWriter, by making a dummy call through the }
{ QDProcs.lineProc bottleneck. Pen size and pen location are preserved. }
Another unwanted effect is related to the PostScript LaserWriter driver’s multiple internal buffering of generated PostScript code. The PostScript code generated for text drawing instructions (which usually involves font queries and, sometimes, font downloading) is buffered independently from the PostScript code inserted by means of picture comments. In certain cases, this results in apparently nonsequential execution of drawing instructions, and may affect clipping regions or may have side effects on the PostScript code you included in picture comments. In order to synchronize the sequence of QuickDraw instructions with the generation of PostScript code, you need to call the following procedure:
PROCEDURE FlushPostScriptState;
{ This routine flushes the buffer maintained by the LaserWriter driver. }
{ All PostScript, generated either by the app or by the LaserWriter }
{ driver, will be sent to the device. }
BEGIN
PicComment(PostScriptBegin, 0, NIL);
PicComment(PostScriptEnd, 0, NIL);
END;
In the following discussion of picture comments, we’ll refer to these two utility routines as appropriate.
Text Rotation
Comments: TextBegin, TextCenter, TextEnd
These comments give access to PostScript’s capabilities of rotating, flipping, and justifying text. They are intended for applications likely to be used with PostScript printers (such as desktop publishing and advanced drawing applications), but which don’t want to use PostScript explicitly. Note that some non-PostScript printer drivers support these comments as well. For situations where the comments are not supported (such as the QuickDraw screen, or most QuickDraw printer drivers), you must provide a bitmap represen-tation of the rotated text as an alternative.
Let’s look at sample code right away.
USES PicComments; { See Appendix; defines constants for just and flip and }
{ the structures referred to by TTxtPicHdl and TCenterHdl.}
PROCEDURE QDStringRotation(s: Str255; ctr: Point;
just, flip: Integer; rot: Fixed); EXTERNAL;
{ This routine should generate a bitmap of the rotated and flipped text }
{ and use CopyBits to draw it to the grafPort. Left as an exercise ... }
{ PostScript graphics state now has rotated/flipped coordinates. }
oldClip := NewRgn;
GetClip(oldClip);
SetRect(zeroRect,0,0,0,0);
ClipRect(zeroRect); { Hides the following DrawString from QuickDraw }
DrawString(s); { in the rotated PostScript environment. }
ClipRect(oldClip^^.rgnBBox);
{ Now the "fallback" bitmap representation; see the comments above }
{ at the declaration of the QDStringRotation procedure. }
QDStringRotation(s, ctr, just, flip, rot);
PicComment(TextEnd,0,NIL); { Set environment back to the original state }
DisposHandle(Handle(hT));
DisposHandle(Handle(hC));
MoveTo(pt.h,pt.v); { to preserve the pen position }
END;
The preceding discussion about including both QuickDraw and PostScript representations and the comments included in the source code say it all: The conventions tied to the usage of the TextBegin and TextEnd picture comments allow you to take advantage of a printer driver’s implementation of high-resolution text rotation, while including a bitmapped representation for where the comments are not supported.
Some Additional Hints
• Because of QuickDraw’s orientation of the vertical coordinate axis, the rotation angle is measured clockwise. Nothing prevents us from using the negative angle if we are used to the counterclockwise orientation.
• The angle is measured in degrees (0..360), and passed as a Fixed type number (that is, if taken as a LongInt value, you have to divide it by 65536 to obtain the angle in degrees). For integer angles, it is possible to use a reduced TTxtPicRec structure that does not contain the tRotFrac field. The PostScript LaserWriter driver uses GetHandleSize(hT) to determine whether it must use the fractional angle in the tRotFrac field. To be safe, always set the tRot field to FixRound(tRotFrac) if you go with the extended TTxtPicRec (as we do here).
• It is convenient that clipping regions are ignored between the TextBegin and TextEnd picture comments, because it allows us to clip out the DrawString on printers that don’t support these comments. Unfortunately, this also means that text rotated this way can’t be clipped. If clipping of rotated text is required, you’ll have to do it entirely within PostScript.
• Due to the LaserWriter driver’s internal buffering of generated PostScript code, the effect of ignoring clip regions may be propagated to preceding sections of your drawing instructions. We recommend calling the FlushPostScriptState procedure described earlier immediately before the TextBegin comment.
• The tJus field in the TTxtPicRec, if different from tJusNone, tells the printer driver to maintain either the left, right, or center point of the string without recalculating the interword and intercharacter spacing. The tJusFull value specifies that the original length of the string (on the QuickDraw screen) must be maintained. This is important when the printer font has widths different from those of the screen font, and when you rotate justified blocks of text.
• The tFlip field in the TTxtPicRec specifies horizontal or vertical flipping about the center point specified by the TextCenter comment.
• The TextCenter comment specifies the center of rotation for any text enclosed within the TextBegin and TextEnd calls, as an offset to the location of the current point. The rotation is achieved by changing PostScript’s coordinate system. A sequence of DrawString – MoveTo instructions is rotated as a whole until TextEnd is encountered.
• Some versions of double-byte Kanji systems print Kanji characters by calling CopyBits instead of calling standard text drawing routines. This means the comments in the Text Rotation family cannot be used with these fonts. Instead, use the Graphics Rotation comment family described later in this Note.
When drawing to a printing grafPort, the selected printer driver does a lot of work “behind the scenes” to try to maintain the infamous “What-You-See-Is-What-You-Get” (WYSIWYG) metaphor from the screen to the paper, and generally to make the printed output look as good as possible. Depending on the target device, the printer driver, and the configuration of fonts in the system, the font you draw text with may be scaled, smoothed, remapped, or even replaced by a font built into the printer. In nearly all cases where the device resolution of the printer is different from QuickDraw’s “hard-coded” 72-dpi screen resolution, the width of text rendered on the printer is different from the text width on the screen. This is due to nonproportionally scaling bitmapped fonts, different character widths after font substitution, and rounding errors of fractional character widths on the screen. The difference in the width of a line of text is called the line layout error.
The printer driver is responsible for adjusting the word and character spacing in the printed output so that the two widths are identical. If it doesn’t, apparently fully justified text on the screen may appear ragged on the paper, and certain lines of text may extend beyond the right border and be badly clipped. Many existing applications make this task really difficult for the printer drivers (don’t blame them, though!). They position the words (or even characters) separately on a line, and the printer driver has to figure out how to collect the complete line before applying its line layout algorithm to distribute the difference of the text widths into word and character spacing. Given the uneven distribution of the character width differences, and the requirement of achieving good typographical quality in the printed output, it is unavoidable that the position and width of a word within a justified line differs slightly from what appears on the screen; only the length of the whole line is maintained.
In computing the required line layout adjustments, the LaserWriter driver proceeds as follows:
1. It collects text coming through the printing grafPort’s textProc bottleneck, and heuristically puts it together into what it “believes” is a logically contiguous line of text. This includes text moved vertically away from the baseline, to take care of indices or exponents in the text. The process of accumulating text is stopped when the LaserWriter driver detects that the horizontal component of the pen position has changed since the previous text drawing instruction, or when picture comments like TextBegin, TextEnd, StringBegin, StringEnd are encountered.
2. It determines the width of the accumulated logical line of text, both on the screen and on the printer, and distributes the line layout error among the interword and intercharacter spacing of the printed output.
The LineLayoutOff picture comment disables only the second step (distribution of the line layout error); the heuristic algorithm of accumulating text into a logically contiguous piece is not affected. Otherwise, if the character widths of the printer font are different from those of the screen font, and if the text contains exponents or indices, the latter would often be misplaced.
The following code fragment shows a probably unexpected consequence of this behavior. We draw a line in two pieces three times. A vertical line shows the starting pen position of the second DrawString call. The second line is enclosed by LineLayoutOff and LineLayoutOn picture comments.
PROCEDURE ObserveLineLayout;
CONST
testString1 = 'Whatever you like, preferably ';
testString2 = 'with spaces, long and short words';
fontName = 'New York';
fontSize = 14;
x0 = 20; { starting point }
y0 = 40;
h = 30; { line height }
VAR
familyID: Integer;
w, y : Integer;
BEGIN
GetFNum(fontName, familyID);
TextFont(familyID);
TextSize(fontSize);
w := StringWidth(testString1);
y := y0;
MoveTo(x0 + w, y - h);
Line(0, 4 * h); { This is to estimate the difference. }
{ Draw the first line, in two pieces. }
{ This is the default line layout behavior of the LaserWriter driver. }
MoveTo(x0, y);
DrawString(testString1);
MoveTo(x0 + w, y);
DrawString(testString2);
{ Draw the second line, in the same way as above. }
{ Because of the LineLayoutOff picture comment, the unmodified widths }
{ of the printer font are used. }
y := y + h;
PicComment(LineLayoutOff, 0, NIL);
{ ••• (1) •••}
MoveTo(x0, y);
DrawString(testString1);
MoveTo(x0 + w, y);
{ ••• (2) •••}
DrawString(testString2);
y := y + h;
PicComment(LineLayoutOn, 0, NIL);
{ Back to the original behavior. }
MoveTo(x0, y);
DrawString(testString1);
MoveTo(x0 + w, y);
DrawString(testString2);
END;
And this is (approximately) the output of the ObserveLineLayout (with LaserWriter driver version 7.1.1, and the default setting “Font Substitution enabled”):
Figure 1—Effect of the LineLayoutOff comment
For most noticeable effects, we choose the bitmapped New York font, such that the LaserWriter driver substitutes PostScript Times (note that there are no line layout problems with TrueType fonts, unless the TrueType font has the same name and different cha-rac-ter widths as a printer-resident PostScript font). The screen font New York is larger than the PostScript font Times, and in the first and third lines, the printer driver (after accumulating testString1 and testString2 into one logical line) distributes the line layout error (mainly) among the spaces between words. You may even notice that the starting point of testString2 (“with ...”) has been slightly moved to the left in the process. The width of the whole line, however, is the same as on the screen.
The second line, where the LineLayoutOff comment is active, demonstrates a dramatic counterexample to the popular belief that this picture comment is here to assure precise positioning of text. It seems the opposite is true, and the LaserWriter driver has deliberately ignored the MoveTo(x0+w,y) instruction! What we would have expected is this:
Figure 2—Desired result of the LineLayoutOff comment
The attentive reader already knows the explanation. As mentioned earlier, we must break the LaserWriter driver’s heuristic line accumulation algorithm before drawing testString2. Short of adequate documentation, developers have found out that a FlushGrafPortState call right after the MoveTo(x0+w,y) instruction has the desired effect (see {••• (2) •••} in the code snippet given earlier). Unfortunately, it creates quite a lot of overhead in the pictures, and penalizes all printer drivers that don’t need it. A better solution is to use the StringBegin and StringEnd picture comments at the markers {••• (1) •••} and {••• (2) •••} in the code shown earlier. This indicates that testString1 is to be considered a logically independent text entity, and must not be put together with any other pieces of text coming through the textProc bottleneck. The overhead of these comments is much smaller, and they don’t affect other printer drivers at all.
The ClientLineLayout picture comment, supported by the (PostScript) LaserWriter driver, has never been documented. Its effect is rather subtle and very specific to the PostScript LaserWriter driver. Basically, it allows the application to redefine the character that absorbs the major part of the line layout error (usually the space character), and the percentages of the “major” and “minor” parts of the line layout error (usually 80 percent versus 20 percent). The “minor” part is distributed across intercharacter spacing.
Only very ambitious page layout applications might be interested in this functio-na-lity; but then, they should rather aim at a more general scheme of line layout control that does not rely upon this very driver-specific picture comment.
The PicComment.p interface (see the Appendix) describes the TClientLLRecord structure passed through the handle parameter to the picture comment. If you want, feel free to experiment with it; we recommend, however, that you do not use this picture comment in your application.
Caveats
• Some older printer drivers supporting the LineLayoutOff picture comment are unable to correctly obey a subsequent LineLayoutOn picture comment.
• Don’t forget that if you use LineLayoutOff, the burden of “WYSIWYG” is now on your shoulders, and not the printer driver’s.
• A previous version of this Note said that setting the Font Manager’s FractEnable global to TRUE implied the effect of the LineLayoutOff picture comment. As it turned out, the statement was based on observations with a specific (older) version of the LaserWriter driver, and is not true in general. The setting of FractEnable does have some more or less subtle effects on the line layout algorithm, however; and this is quite plausible. Similarly, the results of combining the picture comments LineLayoutOff and LineLayoutOn with calls to SpaceExtra (Inside Macintosh Volume I, page 172) or CharExtra (Inside Macintosh Volume V, page 77) are sometimes unpredictable, depending on the particular printer driver.
And Finally the Good News
Given that the effect of the LineLayoutOff and LineLayoutOn comments does not require any changes in your printing code, you don’t have to worry whether or not a particular driver supports them. They are useful mainly when you’re sure you want no external assistance in computing word and character spacing for full justification, or when you need precise control over the horizontal placement of words and characters (such as in forms or tabulated text) and understand how to achieve this.
String Delimitation
Comments: StringBegin, StringEnd
These comments allow applications to specify the logical beginning and end of a string, possibly drawn with multiple calls to a QuickDraw text drawing routine (such as DrawChar). If this was their only raison d’être, they would have no relationship with the PostScript LaserWriter driver. But, as already let out in the preceding section on line layout, they are important to notify the printer driver that it should consider the text coming through the textProc bottleneck between StringBegin and StringEnd as an independent entity. Otherwise, the driver might continue to perform its heuristic accumulation of text drawing instructions for the same line, and defeat your text positioning intentions. Indeed, both StringBegin and StringEnd trigger the generation of PostScript instructions for drawing the text that has been accumulated in a line layout buffer, and reinitialize the internal variables for line layout computations. In other words, you need these picture comments to turn the LaserWriter driver’s line layout behavior completely off.
PostScript has the built-in capability of drawing cubic Bézier curve sections (see the PostScript Language Reference Manual, Second Edition, page 393). This is convenient for “smoothing” of polygons. The polygon-related picture comments have been provided to give applications easy access to this PostScript feature, with provision for including a QuickDraw approximation of the curve.
Schematically, the polygon comments are used as follows:
PolyBeginComment; { Put the PostScript driver into “polygon mode.” }
ClipRect(zeroRect); { Hide the following from QuickDraw. }
PolyCloseComment; { Optionally, if “closed” smoothing desired. }
PolySmoothComment; { Tell the driver to draw a Bézier curve. }
DrawPolygon; { Invisible for QuickDraw; PostScript output = curve. }
PolyIgnoreComment; { The driver will ignore the following line drawing. }
SetClip(origClipRgn); { Make it visible for QuickDraw. }
DrawQDPolygon; { Usually, a QuickDraw approximation of the curve. }
PolyEndComment; { PostScript driver resumes standard mode. }
A piece of sample code is sometimes worth more than one or two pictures; below, you’ll find both. For clarity and completeness of the exposition, we provide the coordinate definition of the polygons through arrays of Points, initialized in a preliminary DefineVertices procedure. You can enclose the PolygonDemo procedure between OpenPicture and ClosePicture calls to create a picture containing both QuickDraw and PostScript representations (see Figures 3 and 4), or you can use it as is when a printing page is open.
USES PicComments;
{ See Appendix of this Note for the definition of the TPolyRec structure. }
CONST
kN = 4; { number of vertices for PostScript }
kM = 6; { number of vertices for QuickDraw approximation }
TYPE
PointArray = array[0..0] of Point; { range checking OFF }
PointArrayPtr = ^PointArray;
PROCEDURE DefineVertices(VAR p,q: PointArrayPtr);
CONST
cx = 280;
cy = 280;
r0 = 200;
BEGIN
{ The array p^ contains the control points for the Bézier curve: }
SetPt(p^[0],cx + r0,cy);
SetPt(p^[1],cx,cy + r0);
SetPt(p^[2],cx - r0,cy);
SetPt(p^[3],cx,cy - r0);
p^[4] := p^[0];
{ q^ contains the points for a crude polygon approximation of the curve: }
q^[0] := p^[0];
SetPt(q^[1],cx,cy + round(0.7 * (p^[1].v - cy)));
SetPt(q^[2],(p^[1].h + p^[2].h) DIV 2,(p^[1].v + p^[2].v) DIV 2);
SetPt(q^[3],cx + round(0.8 * (p^[2].h - cx)),cy);
SetPt(q^[4],q^[2].h,cy + cy - q^[2].v);
SetPt(q^[5],q^[1].h,cy + cy - q^[1].v);
q^[6] := q^[0];
END;
PROCEDURE PolygonDemo;
VAR
p,q: PointArrayPtr;
aPolyVerbH: TPolyVerbHdl;
i: Integer;
clipRgn, polyRgn: RgnHandle;
zeroRect: Rect;
BEGIN
p := PointArrayPtr(NewPtr(SizeOf(Point) * (kN + 1)));
FrameRgn(polyRgn); { Or FillRgn, if fPolyFill above is TRUE. }
PicComment(PolyEnd,0,NIL);
DisposHandle(Handle(aPolyVerbH));
DisposeRgn(polyRgn);
DisposPtr(Ptr(p));
DisposPtr(Ptr(q));
END;
Figure 3-Output on Quickdraw printer; Figure 4-Output on PostScript printer
Additional Comments and Explanations
1. The fPolyFrame and fPolyFill fields of the TPolyRec record are self-explanatory. The fPolyClose flag is redundant with the PolyClose picture comment, but is included for the convenience of the LaserWriter driver. It is often misunderstood. It does not mean the polygon is being closed automatically, such as with the PostScript closepath operator; instead, it affects the shape of the smooth curve. Figure 4 shows the result for fPolyClose = FALSE; the start and end point of the polygon is distinguished. In the case of fPolyClose = TRUE, all vertices of the polygon are treated in the same manner, and the resulting curve resembles a circle (in this case).
2. The anonymous fields f3..f7 are reserved and should be set to zero (that is, FALSE).
3. The polygon is drawn at the current pen location when the PolyBegin comment is received.
4. In general (and in this example), you do not need to open a region, collect the line segments in the region, and draw the polygon through FrameRgn. It is demonstrated here only to prepare you for situations where you want to fill the polygon with a pattern. You cannot open a polygon and use FillPoly, because the PostScript driver “owns” the polygon concept at this point and captures—and ignores—all line drawing between the PolyIgnore and PolyEnd comment. Regions do not interfere with polygons, however, and can be used to paint or fill the polygonal shape.
Caveats
PostScript Level 1 has problems with very large polygons (more than about 1000 points). The workaround is to subdivide the large polygon into several smaller ones.
You cannot combine the polygon picture comments with other comments such as the rotation comments or the DashedLine comment. It’s just another limitation—no comment.
Dashed Lines
Comments: DashedLine, DashedStop
PostScript allows applications to draw precisely dashed lines with a given dash pattern in every direction (see the setdash operator, PostScript Language Reference Manual, Second Edition, page 500). The QuickDraw ersatz of setting the pen pattern appears to be awkward at best; the result depends very much on the direction of the line. Coding correctly dashed lines in QuickDraw is quite a hassle and rather clumsy. This is why the DashedLine and DashedStop picture comments have been provided for applications where dashed lines are important and used frequently. Applications can take advantage of these comments when printing to a PostScript printer.
The DashedLine comment tells the driver that the line drawing instructions following the comment should be dashed according to the parameters in the TDashedLine structure (see the Appendix). These parameters closely correspond to the parameters passed to the PostScript setdash operator. Only the centered field of the TDashedLine structure is not currently supported by the LaserWriter driver. It should be set to 0 in case support for centering is added in the future.
Unlike the picture comments for text rotation or even polygon smoothing, the DashedLine picture comment should not be supported by a non-PostScript driver. The only way to include representations of dashed lines with and without usage of the DashedLine picture comment is to make the following assumption: If the DashedLine comment is supported, then the printer is a PostScript printer, and the PostScriptBegin/PostScriptEnd bracket may be used to hide the QuickDraw imaging from the printer. Remember that non-PostScript printer drivers must not ignore QuickDraw imaging within PostScriptBegin and PostScriptEnd!
But we still need a trick to hide the line drawing instructions within the DashedLine – DashedStop bracket from QuickDraw. Here comes the “magic pen mode” to our rescue:
PROCEDURE DashDemo;
CONST
magicPen = 23; { the infamous penMode ! }
cx = 280;
cy = 280;
r0 = 200;
VAR
dashHdl: TDashedLineHdl;
i: Integer;
a, rad : Extended;
BEGIN
PenSize(2,2);
{ First the PostScript picture comment version. }
{ The "magic pen mode" 23 makes the line drawing invisible for QuickDraw. }
{ Now, the QuickDraw version. The PostScript driver must ignore it, }
{ so we enclose it between PostScriptBegin and PostScriptEnd comments.}
PicComment(PostScriptBegin, 0, NIL);
PenSize(2,2);
FOR i := 0 TO 9 DO BEGIN
MoveTo(cx,cy);
DashedQDLine(round(r0 * cos(i * 20 * rad)),
- round(r0 * sin(i * 20 * rad)), dashHdl);
END;
PicComment(PostScriptEnd,0,NIL);
END;
By the way: The DashedQDLine procedure is intentionally missing. It’s not precisely the subject of this Note, and thus, again, is left as a spare-time exercise for the reader.
Caveat
As mentioned earlier, the current version of the PostScript LaserWriter driver produces poor results when the DashedLine picture comment is applied to polygons. Just don’t do it!
Fractional Line Width
Comment: SetLineWidth
QuickDraw’s design is based on a fixed 72-dpi resolution. Even when printing to a high-resolution device, the Printing Manager presents the printing grafPort, corresponding to the printable area of the page, in the integer-valued QuickDraw coordinate system with 72 dpi. Applications can use PrGeneral to image at higher device resolutions (see Inside Macintosh Volume V, page 410), but this is useful mainly for immediate printing. As a consequence, lines are usually always at least 1/72 inch wide, corresponding to the smallest pen size (1,1). For a 300-dpi device like the LaserWriter, this is disappointing.
The SetLineWidth comment allows an application to set the width of a line to any fractional value. A value of 1/4 approximately corresponds to a “hairline” on a 300 dpi LaserWriter. Curiously (but conveniently), a QuickDraw Point structure is passed in the PicComment’s data handle, the vertical coordinate representing the denominator, and the horizontal coordinate the numerator of the fraction.
Unfortunately, it is not implemented in all high-resolution QuickDraw printers; and if it is (as in the LaserWriter SC), it works differently than in PostScript printer drivers. Moreover, there is no possibility to include alternative imaging instructions in case SetLineWidth is not supported. While this is not much of a loss for hairlines, it prevents us from using the comment for fractional widths > 1, where the alternative would be to include a PenSize call with rounded arguments. Another drawback may be that, allegedly, there are plotter drivers out there that abuse this comment to set the pen color—clearly an unpleasant situation.
The difference in the implementation of the SetLineWidth comment between the PostScript LaserWriter driver and the LaserWriter SC appears as soon as SetLineWidth is used for the second time. The PostScript driver keeps an internal line scaling factor; this factor is initialized to 1.0 when a job is started. Each number passed through SetLineWidth is multiplied by the current internal scaling factor to get the effective scaling factor for the pen size. The LaserWriter SC driver, on the other hand, replaces its current scaling factor for the pen size completely by the new value passed through SetLineWidth. In order to support both implementations, you must always use an additional SetLineWidth step in order to reset the PostScript driver line width to 1.0, before scaling to the new value.
Example
Let’s say you have set the line width to 0.25, and want to replace it by a line width of 0.5. The following two SetLineWidth comments will have the desired effect on both PostScript (PS) and QuickDraw (QD) drivers that implement the SetLineWidth comment. You don’t care about the temporary line width of 4.0 on the QuickDraw driver.
Current Line Width Parameter Passed New Line Width
PS driver QD driver in SetLineWidth PS Driver QD Driver
0.25 0.25 4/1 1.0 4.0
1.0 4.0 1/2 0.5 0.5
The following sample code gives the expected results only on a PostScript LaserWriter and on QuickDraw printer drivers that have the SetLineWidth comment implemented.
oldWidth,newWidth: TLineWidth; { actually a "Point" }
i,j,y: Integer;
BEGIN
PenNormal;
y := y0;
SetPt(oldWidth,1,1); { initial linewidth = 1.0 }
FOR i := 1 TO 5 DO BEGIN
SetPt(newWidth,4,i);
{ want to set it to i/4 = 0.25, 0.50, 0.75 ... }
SetNewLineWidth(oldWidth,newWidth);
MoveTo(x0, y);
Line(d0, 0);
y := y + e0;
oldWidth := newWidth;
END;
END;
A Slight Imperfection
If you experiment with the above code and draw a whole series of hairlines, you will see (depending on the values of e0 and kN) that certain lines appear thicker than they should be. This is due to rasterization effects in PostScript’s scan conversion algorithm when the line width is close to the device pixel size. In many cases, the PostScript LaserWriter driver tries to compensate for this by rounding coordinates to the 300-dpi grid. If you include SetLineWidth (or, by the way, DashedLine) picture comments, however, this does not work. PostScript Level 2 addresses this problem by means of an optional stroke adjustment feature (see the PostScript Language Reference Manual, Second Edition, pages 322 and 515).
Graphics Rotation
Comments: RotateBegin, RotateCenter, RotateEnd
Like the picture comments discussed earlier in this Note in the section “Text Rotation,” the graphics rotation picture comments provide a method of rotating QuickDraw objects on PostScript devices. Instead of having QuickDraw perform the rotation, the printer driver rotates the entire PostScript coordinate space so that everything drawn between RotateBegin and RotateEnd will be rotated on the printer itself. This includes text drawing! You specify the center of rotation with RotateCenter and the angle of the rotation, together possibly with horizontal or vertical flipping, through the TRotation record (see the interface definitions in the Appendix).
Unlike text rotation, you must insert the RotateCenter comment and pass the relative offset to the center of rotation before you use the RotateBegin picture comment. The point passed to RotateCenter specifies the offset from the anchor point of the first object drawn after RotateBegin to the desired center of rotation. Once you set up the rotation parameters with RotateCenter and RotateBegin, you can draw the graphics objects you want to rotate.
Bad news: In order to include a QuickDraw representation of the rotated objects in case the rotation comments are not supported, we have to assume (again) that only PostScript drivers implement these comments. The only way to hide the QuickDraw substitute from the driver is to surround it by PostScriptBegin and PostScriptEnd comments; and, similarly to the DashedLine comment, we need to use the “magic pen mode” (23) to hide the unrotated drawing between RotateBegin and RotateEnd from QuickDraw. The following sample demonstrates this:
The PostScript comments tell the picture interpreter (usually the LaserWriter driver) that the application is going to communicate with the LaserWriter directly using PostScript code instead of QuickDraw. All QuickDraw drawing instructions between the PostScriptBegin and PostScriptEnd picture comments are ignored. The driver sends the PostScript text contained in the PostScriptHandle data to the printer with no preprocessing and no error checking. When the application is finished sending PostScript, the PostScriptEnd comment tells the printer driver to resume normal QuickDraw mode. The driver uses the PostScript save and restore operators to preserve the state of the PostScript interpreter across the section enclosed by PostScriptBegin and PostScriptEnd. Some applications do not want to restore the previous state of the PostScript interpreter after including their PostScript code; for these situations, the PSBeginNoSave comment is a replacement for PostScriptBegin that does not preserve the state. Clearly, this comment should be used with extreme caution.
Some state information may be stored in global variables, so nesting PostScriptBegin (or PSBeginNoSave) and PostScriptEnd comments is not allowed.
The PostScriptHandle comment gives developers direct access to PostScript from applications. Instead of having the LaserWriter driver convert QuickDraw calls into the corresponding PostScript code, the application can generate its own PostScript, and transmit it to the printer or include it in a picture through the data handle of the PicComment procedure. The handle contains pure ASCII text; the valid length of the data is specified in the PicComment’s size parameter. Don’t forget to terminate the PostScript text at least with a space character, or better with a carriage return (ASCII $0D), so that it is separated from the following PostScript instructions (either yours, or the printer driver’s).
You must still use PostScriptBegin (or PSBeginNoSave) and PostScriptEnd around PostScriptHandle comments or the LaserWriter driver will not properly save and restore the PostScript drawing environment.
As with all picture comments, the handle you pass belongs to you and you must dispose of it when you’re finished with it.
PROCEDURE PostScriptLine(s: Str255);
{ A utility procedure to transmit a string of PostScript code through }
{ the PostScriptHandle picture comment to the PostScript printer. }
{ It should be called only between PostScriptBegin and PostScriptEnd }
{ picture comments. }
VAR
h: Handle;
BEGIN
h := NewHandle(256);
IF h = NIL THEN DebugStr('NewHandle failed');
BlockMove(@s[1],h^, Length(s));
PicComment(PostScriptHandle, Length(s), h);
h^^ := 13;
PicComment(PostScriptHandle, 1, h); { add a carriage return }
{ Let's test to see if the definition from above is still avail-}
{ able. This assumes that no font downloading has occurred. }
PicComment(PostScriptBegin,0,NIL);
PostScriptLine('//userdict /myFrameRect get exec ');
PicComment(PostScriptEnd,0,NIL);
END;
Caveat
If you choose to use PostScript directly in your pictures, be very careful not to make assumptions about Apple’s "md" dictionary (essentially the contents of the former LaserPrep file). Otherwise, your pictures will not print correctly with future versions of the PostScript LaserWriter driver. Also, be aware of compatibility problems within the PostScript world, and watch out for printers with PostScript Level 1 and PostScript Level 2 interpreters, and “PostScript-compatible” printers (PostScript clones).
FormsPrinting Picture Comments
Comments: FormsPrinting, EndFormsPrinting
The FormsPrinting comment tells the PostScript LaserWriter driver not to clear its page buffer after printing a page. EndFormsPrinting turns this mode off. When the page is completed, the application must erase the areas that need to be updated and draw the new information. The graphics that make up the form are drawn only once per page, which may improve performance. Currently, you need to write special printing code for the PostScript LaserWriter driver if you want to use this comment.
(More or Less) Obsolete PostScript Picture Comments
Comments: SetGrayLevel,
TextIsPostScript, ResourcePS, PostScriptFile
The SetGrayLevel picture comment was designed to provide access to the PostScript setgray operator while still drawing with QuickDraw in black-and-white mode. In practice, this turned out to be not so useful, however. For most drawing operations, the printer driver sets the gray level to match the foreground color currently stored in the printing grafPort, and the effect of the SetGrayLevel comment is often unpredictable. If direct access to the PostScript setgray operator seems nevertheless desirable, it is easy to include the instruction in a PostScriptHandle comment.
The TextIsPostScript picture comment takes all the text coming through standard QuickDraw text drawing calls (DrawChar, DrawString, DrawText, and anything else that eventually calls the StdText bottleneck), and interprets it as a PostScript program. There is no good reason to use this picture comment, but there is one important reason not to use it: Printer drivers that do not deal with the TextIsPostScript comment will print the PostScript text instead of interpreting it! If you need to transmit pure PostScript code directly to a printer that understands it, use the PostScriptHandle comment, and include a QuickDraw representation for all other printer drivers.
The ResourcePS picture comment loads PostScript code from a specified resource. The resource file is expected to be open at the time that the ResourcePS comment is used. Under background printing, there are no guarantees the file will still be open when the Printing Manager needs it. For this reason alone, you should forget about this comment. If you want to keep PostScript instructions in a resource, it is easy to write a small routine that loads the resources and sends their contents using the PostScriptHandle comment described earlier in this Note.
PostScriptFile has the same problems as ResourcePS described above. Basically, the Printing Manager cannot guarantee that the file will be available when it’s needed.
Appendix: Pascal Interface for Picture Comments
(File PicComments.p)
CONST
TextBegin = 150;
TextEnd = 151;
StringBegin = 152;
StringEnd = 153;
TextCenter = 154;
LineLayoutOff = 155;
LineLayoutOn = 156;
ClientLineLayout = 157;
PolyBegin = 160;
PolyEnd = 161;
PolyIgnore = 163;
PolySmooth = 164;
PolyClose = 165;
DashedLine = 180;
DashedStop = 181;
SetLineWidth = 182;
PostScriptBegin = 190;
PostScriptEnd = 191;
PostScriptHandle = 192;
PostScriptFile = 193;
TextIsPostScript = 194;
ResourcePS = 195;
PSBeginNoSave = 196;
SetGrayLevel = 197;
RotateBegin = 200;
RotateEnd = 201;
RotateCenter = 202;
FormsPrinting = 210;
EndFormsPrinting = 211;
tJusNone = 0; { values for the tJus field of the TTxtPicRec record }
tJusLeft = 1;
tJusCenter = 2;
tJusRight = 3;
tJusFull = 4;
tFlipNone = 0; { values for the tFlip field of the TTxtPicRec record }
tFlipHorizontal = 1;
tFlipVertical = 2;
TYPE
TTxtPicHdl = ^TTxtPicPtr;
TTxtPicPtr = ^TTxtPicRec;
TTxtPicRec = PACKED RECORD
tJus : Byte;
tFlip : Byte;
tAngle: Integer; { clockwise rotation in degrees 0..360 }
tLine : Byte; { Unused/Ignored }
tCmnt : Byte; { reserved }
tAngleFixed: Fixed; { same as "tAngle" in Fixed precision }
END; { TTxtPicRec }
TRotationHdl = ^TRotationPtr;
TRotationPtr = ^TRotation;
TRotationRec = RECORD
rFlip: Integer;
rAngle: Integer; { clockwise rotation in degrees 0..360 }
rAngleFixed: Fixed; { same as "rAngle" in Fixed precision }
END; { TRotationRec }
TCenterHdl = ^TCenterPtr;
TCenterPtr = ^TCenter;
TCenterRec = RECORD {offset from current pen location to center of rotation}
y: Fixed;
x: Fixed;
END; { TCenterRec }
TPolyVerbHdl = ^TPolyVerbPtr;
TPolyVerbPtr = ^TPolyVerbRec;
TPolyVerbRec = PACKED RECORD
f7,f6,f5,f4, f3, { reserved }
fPolyClose, { TRUE = smoothing across endpoint.}
fPolyFill, { TRUE = Polygon should be filled. }
fPolyFrame: BOOLEAN; { TRUE = Polygon should be framed. }
END;
TDashedLineHdl = ^TDashedLinePtr;
TDashedLinePtr = ^TDashedLineRec;
TDashedLineRec = PACKED RECORD
offset : SignedByte; { offset into pattern for } { first dash }
centered : SignedByte; { (Ignored) }
intervals: ARRAY [0..5] { Array of dash intervals }
OF SignedByte; { intervals[0] = number }
END; { of interval specs. }
TLineWidthHdl = ^TLineWidthPtr;
TLineWidthPtr = ^TLineWidth;
TLineWidth = Point; { v = numerator, h = denominator. }
TClientLLHdl = ^TClientLLPtr; { used in the ClientLineLayout picture comment }
TClientLLPtr = ^TClientLLRec;
TClientLLRec = RECORD
chCount : Integer; { Apply for so many characters. }
major : Fixed; { percentage of line layout error to be }
{ distributed among space characters. }
spcChar : Integer; { code of character that is to absorb }
{ the "major" line layout error }
minor : Fixed; { percentage of intercharacter distrib. }
ulLength: Fixed; { underline length. }
END;
Further Reference:
• PostScript Language Reference Manual, Adobe Systems Inc.
• Inside Macintosh, Volumes II, V, and VI
• LaserWriter Reference Manual, Addison-Wesley
• Macintosh Technical Note M.IM.AppPictComments —
Every Picture [Comment] Tells Its Story, Don’t It?
• Macintosh Technical Note M.IM.PictAndPrinting —
Pictures and the Printing Manager
• develop Issue 3, “Meet PrGeneral” by Pete “Luke” Alexander
Adobe is a trademark of Adobe Systems Incorporated.
PostScript is a registered trademark of Adobe Systems Incorporated.
Every Picture [Comment] Tells Its Story, Don’t It?
Imaging M.IM.AppPictComments
Revised by: March 1988
Written by: Rick Blair November 1987
Application-specific picture comment conflict and registration is addressed, along with Developer Technical Support’s method for solving it.
I will assume that the nature and usefulness of picture comments are already well known. The problem I am addressing is that, as it stands, developers must register their comments with us (Developer Technical Support) or run the risk of using the same comments as those used by Apple or within another third party product.
The idea here is to provide a “metacomment” which will contain information about which application owns the comment as well as the comment itself:
data = application signature (i.e. 'MPNT' for MacPaint) = 4 bytes
application “local” kind = 2 bytes
comment data = n bytes
In this way each comment may be specific to an application. It is still up to a developer to publish information about the comments they have defined if they wish them to be understood and used by other programs.
Previously assigned and registered comments will still be valid. This means that those defined for the LaserWriter or MacDraw, for instance, will retain their normal meaning.
Suppose your application (creator = 'MYAP') wanted to define a comment. The appearance of the comment would be as follows (assuming you chose 128 to be the “local” kind for the comment):
kind = 100; data = 'MYAP' [4 bytes] + 128 [2 bytes] + additional data
Further Reference:
• QuickDraw
• Technical Note M.IM.PictComments —
Optimizing for the LaserWriter—Picture Comments
QuickDraw’s Internal Picture Definition
Imagining M.IM.PictureOpcodes
Revised by: Rick Blair November 1986
March 1988
Written by: Ginger Jenigan April 1985
This technical note describes the internal format of the QuickDraw picture data structure. This revision corrects some errors in the opcode descriptions and provides some examples.
This technical note describes the internal definition of the QuickDraw picture. The information given here only applies to QuickDraw picture format version 1.0 (which is always created by Macintoshes without Color QuickDraw). Picture format version 2.0 is documented in the Color QuickDraw chapter of Inside Macintosh. This information should not be used to write your own picture bottleneck procedures; if we add new objects to the picture definition, your program will not be able to operate on pictures created using standard QuickDraw. Your program will not know the size of the new objects and will, therefore, not be able to proceed past the new objects. (What this ultimately means is that you can’t process a new picture with an old bottleneck proc.)
Terms
An opcode is a number that DrawPicture uses to determine what object to draw or what mode to change for subsequent drawing. The following list gives the opcode, the name of the object (or mode), the associated data, and the total size of the opcode and data. To better interpret the sizes, please refer to page I-91 of the Using Assembly Language chapter of Inside Macintosh. For types not described there, here is a quick list:
opcode byte
mode word
point 4 bytes
0..255 byte
–128..127 signed byte
rect 8 bytes
poly 10+ bytes (starts with word size for poly (incl. size word)
region 10+ bytes (starts with word size for region (incl. size word)
fixed point long
pattern 8 bytes
rowbytes word (always even)
bit data rowbytes * (bounds.bottom - bounds.top) bytes
Each picture definition begins with a picsize (word), then a picframe (rect), and then the picture definition, which consists of a combination of the following opcodes:
Opcode Name Additional Data Total Size (bytes)
00 NOP none 1
01 clipRgn rgn 1+rgn
02 bkPat pattern 9
03 txFont font (word) 3
04 txFace face (byte) 2
05 txMode mode (word) 3
06 spExtra extra (fixed point) 5
07 pnSize pnSize (point) 5
08 pnMode mode (word) 3
09 pnPat pattern 9
0A thePat pattern 9
0B ovSize point 5
0C origin dh, dv (words) 5
0D txSize size (word) 3
0E fgColor color (long) 5
0F bkColor color (long) 5
10 txRatio numer (point), denom (point) 9
11 picVersion version (byte) 2
20 line pnLoc ( point ), newPt ( point ) 9
21 line from newPt ( point ) 5
22 short line pnLoc ( point ); dh, dv (-128..127) 7
23 short line from dh, dv (-128..127) 3
28 long text txLoc ( point ), count (0..255), text 6+text
29 DH text dh (0..255), count (0..255), text 3+text
2A DV text dv (0..255), count (0..255), text 3+text
2B DHDV text dh, dv (0..255), count (0..255), text 4+text
30 frameRect rect 9
31 paintRect rect 9
32 eraseRect rect 9
33 invertRect rect 9
34 fillRect rect 9
38 frameSameRect rect 1
39 paintSameRect rect 1
3A eraseSameRect rect 1
3B invertSameRect rect 1
3C fillSameRect rect 1
40 frameRRect rect ( ovalwidth, height; see 1, below ) 9
41 paintRRect rect ( ovalwidth, height; see 1, below ) 9
42 eraseRRect rect ( ovalwidth, height; see 1, below ) 9
43 invertRRect rect ( ovalwidth, height; see 1, below ) 9
44 fillRRect rect ( ovalwidth, height; see 1, below ) 9
48 frameSameRRect rect 1
49 paintSameRRect rect 1
4A eraseSameRRect rect 1
4B invertSameRRect rect 1
4C fillSameRRect rect 1
Opcode (cont.) Name Additional Data Total Size (bytes)
50 frameOval rect 9
51 paintOval rect 9
52 eraseOval rect 9
53 invertOval rect 9
54 fillOval rect 9
58 frameSameOval rect 1
59 paintSameOval rect 1
5A eraseSameOval rect 1
5B invertSameOval rect 1
5C fillSameOval rect 1
60 frameArc rect, startAngle, arcAngle 13
61 paintArc rect, startAngle, arcAngle 13
62 eraseArc rect, startAngle, arcAngle 13
63 invertArc rect, startAngle, arcAngle 13
64 fillArc rect, startAngle, arcAngle 13
68 frameSameArc startAngle, arcAngle 5
69 paintSameArc startAngle, arcAngle 5
6A eraseSameArc startAngle, arcAngle 5
6B invertSameArc startAngle, arcAngle 5
6C fillSameArc startAngle, arcAngle 5
70 framePoly poly 1+poly
71 paintPoly poly 1+poly
72 erasePoly poly 1+poly
73 invertPoly poly 1+poly
74 fillPoly poly 1+poly
78 frameSamePoly (not yet implemented—same as 70, etc.) 1
79 paintSamePoly (not yet implemented) 1
7A eraseSamePoly (not yet implemented) 1
7B invertSamePoly (not yet implemented) 1
7C fillSamePoly (not yet implemented) 1
80 frameRgn rgn 1+rgn
81 paintRgn rgn 1+rgn
82 eraseRgn rgn 1+rgn
83 invertRgn rgn 1+rgn
84 fillRgn rgn 1+rgn
88 frameSameRgn (not yet implemented—same as 80, etc.) 1
maskRgn, packed bitData for each row packed bitData
A0 shortComment kind(word) 3
A1 longComment kind(word), size(word), data 5+data
FF EndOfPicture none 1
Notes
Rounded-corner rectangles use the setting of the ovSize point (see opcode $0B, above).
OpenPicture and DrawPicture set up a default set of port characteristics when they start. When drawing occurs, if the user’s settings don’t match the defaults, mode opcodes are generated. This is why there is usually a clipRgn code after the picVersion: the default clip region is an empty rectangle.
The only savings that the “same” opcodes achieve under the current implementation is for rectangles. DrawPicture keeps track of the last rectangle used and if a “same” opcode is encountered that requests a rectangle, the last rect. will be used (and no rectangle will appear in the opcode’s data).
This last section contains some Pascal program fragments that generate pictures. Each section starts out with the picture itself (yes, they’re dull) followed by the code to create and draw it, and concludes with a commented hex dump of the picture.
{variables used in all examples}
VAR
err: OSErr;
ph: PicHandle;
h: Handle;
r: Rect;
smallr: Rect;
orgr: Rect;
pstate: PenState; {are they in the Rose Bowl, or the state pen?}
90 0002 000A 0014 000F 001C {BitsRect rowbytes bounds (note that bounds is wider than smallr)}
000A 0014 000F 0019 {srcRect}
0000 0000 0014 001E {dstRect}
00 06 {mode=notSrcXor}
0000 0000 0000 0000 0000 {5 rows of empty bitmap (we copied from a
still-blank window)}
FF {fin}
Further Reference:
• QuickDraw
• Color QuickDraw
• Using Assembly Language
• Technical Note #59—Pictures and Clip Regions
Picture Utility Q&As
Imaging M.IM.PictUtil.Q&As
Revised by: Developer Support Center October 1992
Written by: Developer Support Center October 1990
This Technical Note contains a collection of Q&As relating to a specific topic—questions you’ve sent the Developer Support Center (DSC) along with answers from the DSC engineers. While DSC engineers have checked the Q&A content for accuracy, the Q&A Technical Notes don’t have the editing and organization of other Technical Notes. The Q&A function is to get new technical information and updates to you quickly, saving the polish for when the information migrates into reference manuals.
Q&As are now included with Technical Notes to make access to technical updates easier for you. If you have comments or suggestions about Q&A content or distribution, please let us know by sending an AppleLink to DEVFEEDBACK. Apple Partners may send technical questions about Q&A content to DEVSUPPORT for resolution.
New Q&As and Q&As revised this month are marked with a bar in the side margin.
GetPictInfo and QuickTime compressed PICT files
Written: 2/24/92
Last reviewed: 8/1/92
Is it my imagination, or does GetPictInfo return a bit depth of 1 on QuickTime compressed PICT files?
___
Yep! I think this is what happens: The PUP (Picture Utility Package) does not know of the QuickTime Compressed Pixmap opcode (0x8200) and it just skips over the opcode’s data; then it finds the PacksBitRect opcode containing the black-and-white pseudo-alert that you get when you draw the picture in a machine that does not have QuickTime installed, and this is what GetPictInfo reports back.
Trivia: when QuickTime is installed it displays the compressed image and then ignores the following PacksBitRect since QuickTime knows it is only the b&w warning.
NewPalette doesn’t use CTab2Palette to create a palette
Written: 3/12/92
Last reviewed: 8/1/92
I am using the Picture Utilities package to extract the color table from a picture. After getting the color table, I use NewPalette to construct a palette from the color table (usage = tolerant, tolerance = 0). After doing this, the RGB values in the palette don’t always exactly match the RGB values in the source color table, causing my program to fail. If I use NewPalette without a source color table, and then use CTab2Palette to copy the colors over (again with usage = tolerant, tolerance = 0), the colors match exactly.
___
It turns out that NewPalette does not use CTab2Palette, but copies the RGB fields in a strange fashion that is causing the problems you are seeing.
NewPalette copies the high byte in each color table RGB entry into the high byte, as well as the low byte of the corresponding palette entry. Thus, if the color table entry for red was $F000, it becomes $F0F0. This of course makes no difference to QuickDraw since the low byte is not displayed, but if your program expects the low byte to match, then that is where your problem exists.
It is unfortunate that CTab2Palette is different. It turns out that CTab2Palette does not copy the high byte into the low byte unless the pmAnimated bit is set in the usage.
So, the best solution for your code is not to compare the entire RGB value when comparing colors, but rather to compare the high byte of each RGB component separately. If this is not possible, the next best solution is for you to go ahead and use the workaround that you’ve already discovered with CTab2Palette.
It’s unlikely that the the Palette Manager is going to change in the future for something like this. In fact, we would almost call it a “feature” since other developers may even depend on it.
Spooling PixMaps to disk
Written: 6/10/91
Last reviewed: 10/22/91
Do you have sample code for spooling PixMaps to disk in PICT format? Should I write the PICT opcodes to the file myself?
___
Apple recommends that you do not try to write the PICT opcodes yourself. Instead, replace the PutPicProc bottleneck proc, as shown in the Color QuickDraw chapter of Inside Macintosh Volume V on page V-89.
Two additional samples can be found in the sample code contained in the Developer CDs. Look for: “Tools & Apps: Graphics and Imaging: PICT Stuff.” One is a program and the other is an FKEY; both dump the main screen to disk as a PICT. The FKEY is a more complete sample in the sense that it works in black and white as well as Macintosh color computers, but the other is a smaller and simpler sample.
Getting the color usage from a picture under System 6
Written: 6/8/92
Last reviewed: 9/15/92
Do you know how I can obtain the color table of a picture when using a system version that happens to be less than 7.0? The Picture Utilites package seems to be only implemented in System 7.0.
___
You’re correct; the Picture Utilities package is implemented only under System 7. However, it’s possible to write code to duplicate its functionality under System 6. Basically, what you want to do is parse a picture, looking at the colors used for the different objects. How you deal with the colors is up to you.
What you do is replace the QuickDraw bottlenecks in a GrafPort with procedures of your own; in all the bottlenecks for QuickDraw primitives, you can just record the current color as having been used for an object. When you get a StdBits opcode, you’ll have to parse the pixmaps, looking through the image and recording all the colors used. As a shortcut, you could just record all the colors in the color table of the pixmap, if it's an indexed pixel image. After collecting this list of colors and any information on how often they are used, it’s up to you to boil this down into useful information, depending on how you want to use it.
Pictures and Clip Regions
Imaging M.IM.PictClipRegions
Revised by: March 1988
Written by: Jennifer Jernigan January 1986
This note describes a problem that affects creation of QuickDraw pictures.
When a GrafPort is created, the fields in the GrafPort are given default values; one of these is the clip region, which is set to the rectangle (–32767, –32767, 32767, 32767). If you create a picture, then call DrawPicture with a destination rectangle that is not the same size as the picFrame without ever changing the default clip region, nothing will be drawn.
When the picture frame is compared with the destination rectangle and the picture is scaled, the clip region is scaled too. In the process of scaling, the clip region you end up overflows and becomes empty, and your picture doesn’t get drawn. If you call ClipRect(thePort^.portRect) before you record the picture, the picture will be drawn correctly. The clipping on the destination port when playing back the picture is irrelevant: once a picture is incorrectly recorded, it is too late.
Further Reference:
• QuickDraw
Plotting Small Icons
Imaging M.IM.SmallIcons
Revised by: James Beninghaus October 1989
Written by: James Beninghaus & Dennis Hescox August 1989
This Technical Note discusses the 'SICN' resource format and how to plot one in a GrafPort.
Changes since August 1989: Corrected errors in the Pascal code and spruced up the rest.
Introduction
Apple first introduced the 'SICN' resource so that the Script Manager could represent which country specific resources are installed in the system by displaying a small icon in the upper right corner of the menu bar. You can pass a 'SICN' resource to the Notification Manager or Menu Manager, and they will draw it for you automatically—you should continue to let them do so. However, if you want to draw a small icon in your application’s window, then this Note can help.
What does a 'SICN' look like? Following is a 'SICN' representation of a dogcow to help answer this question:
SICN' FatBits
There is reason to believe that this representation is actually a baby dogcow. Due to the protective nature of parent dogcows, young dogcows are rarely seen. This one was spotted during a DTS meeting after it drew attention to itself by crying “moo! woof!”. (Note that this dogcow said “moo! woof!” because it was immature; adult dogcows naturally say, “Moof!”.)
'SICN' Resource
A 'SICN' resource contains any number of small icon bit images. Each small icon in a 'SICN' list describes a 16 by 16 pixel image and requires 32 bytes of storage. Like an 'ICN#' resource, there is no count of the number of icons stored in a 'SICN'. The following 'SICN' resource, in MPW Rez format, contains two small icons:
The Macintosh Toolbox interfaces do not describe all the necessary data structures needed to work with 'SICN' resources. As shown in the following example, defining the 'SICN' type as an array of 16 short integers and the handles and pointers to this array type make life much easier.
Pascal
TYPE
SICN = ARRAY[0 .. 15] of INTEGER;
SICNList = ARRAY[0 .. 0] of SICN;
SICNPtr = ^SICNList;
SICNHand = ^SICNPtr;
C
typedef short SICN[16];
typedef SICN *SICNList;
typedef SICNList *SICNHand;
The Missing Count
The 'SICN' resource does not provide a count to indicate the number of small icons contained within; however, you can easily determine this number by dividing the total size of the resource by the size of a single small icon.
Pascal
CONST
mySICN = 1984;
VAR
theSICN : SICNHand;
theSize : LONGINT;
theCount : LONGINT;
theIndex : LONGINT;
theSICN := SICNHand(GetResource('SICN', mySICN));
IF (theSICN <> NIL) THEN BEGIN
theSize := GetHandleSize(Handle(theSICN));
theCount := theSize DIV sizeof(SICN);
END;
C
#define mySICN 1984
SICNHand theSICN;
long theSize;
long theCount;
long theIndex;
theSICN = (SICNHand) GetResource('SICN', mySICN);
if (theSICN) {
theSize = GetHandleSize((Handle)theSICN);
theCount = theSize / sizeof(SICN);
}
The Plot 'SICN's
The example procedure PlotSICN draws one small icon of a 'SICN' resource. It takes the handle from theSICN and the position in the list from theIndex within the rectangle theRect of the current GrafPort.
Following is an example call to PlotSICN which plots all the small icons in a resource into the same rectangle:
Pascal
SetRect(theRect, 0, 0, 16, 16);
FOR theIndex := 0 TO theCount-1 DO
PlotSICN(theRect, theSICN, theIndex);
C
SetRect(&theRect, 0, 0, 16, 16);
for (theIndex = 0; theIndex < theCount ; ++theIndex)
PlotSICN(&theRect, theSICN, theIndex);
Because PlotSICN uses _CopyBits and _CopyBits can move memory, you should lock the handle to the 'SICN' once the resource is loaded. Notice that the PlotSICN procedure dereferences the 'SICN' handle, adds an offset, and copies the resulting value. If the 'SICN' list moves in memory at this time, the bitmap’s baseAddr is useless.
To play it safe, PlotSICN saves a copy of the master pointer flags associated with the relocatable block, locks the block with a call to _HLock, and restores the flags after calling _CopyBits. You should never examine, set, or clear these flags directly; you should always use the routines which are provided by the Memory Manager and Resource Manager. Note that it is not necessary to check the value of the flag after getting it.
/* restore the resource's locked/unlocked condition */
HSetState((Handle) theSICN, state);
}
}
That Was Easy
Now that you’ve seen it done, it looks pretty easy. With minor modifications, some of the techniques in this Note could also be used to plot a bitmap of any dimension.
Further Reference:
• Inside Macintosh, Volume I, QuickDraw
• Inside Macintosh, Volume I, Toolbox Utilities
• Inside Macintosh, Volume IV, The Memory Manager
• Technical Note M.IM.OffscreenBitMap —
Drawing Into an Off-Screen BitMap
• Technical Note M.IM.DrawingIcons —
Drawing Icons
Principia Off-Screen Graphics Environments
Imaging M.IM.PrincipiaOffScreen
Updated by: Forrest Tanaka March 1992
Written by: Forrest Tanaka October 1991
Inspired by: Jim Friedlander, Rick Blair, and Rich Collyer
Using Color QuickDraw to draw off screen is a common requirement of applications and other kinds of programs that run on the Macintosh. This Note discusses what Color QuickDraw needs in a graphics environment and how to create one for off-screen drawing. A brief discussion of GWorlds, which are off-screen graphics environments that are set up by the system, is given to help you decide whether to use them or the do-it-yourself techniques described in this Note for setting up an off-screen graphics environment. The author’s intent is to provide concepts and routines for creating an off-screen graphics environment, and also to explain why existing routines for off-screen drawing act as they do.
Many, many thanks go to Guillermo Ortiz, Konstantin Othmer, Bruce Leak, and Jon Zap for all their expertise on this subject, Rich Collyer, Rick Blair, and Jim Friedlander for paving the way, and especially to all people who inspired this update by asking great off-screen drawing questions.
Changes since October 1991: A very embarrassing bug was found in CreateOffScreen and UpdateOffScreen. If you try to create a 16- or 32-bit off-screen graphics environment, you’ll just get a paramErr. It won’t do that now.
Off-Screening
The Macintosh, as with every other CPU ever made by Apple, has memory-mapped video. That is, what you see on the screen is just the visual representation of a part of memory that’s reserved for the video hardware (that’s stretching the truth just a bit in the case of the text screens of the original Apple computer, the Apple II line, and the Apple III because there’s also a character generator in those, but the overall process still looks roughly the same). If you change the contents of a memory location in this part of memory, then you’ll see the corresponding location on the screen change when the video hardware draws the next frame or field of video. The resident raster graphics package, QuickDraw in the case of the Macintosh, draws images by stuffing the right values into the right places in the part of memory reserved for the video display. The resulting image on the screen looks like a line or perhaps an oval if you asked QuickDraw to draw a line or an oval, or it could be an entire complex image if you asked QuickDraw to draw one. This is normal, on-screen drawing.
Because video memory is a part of RAM just like any other part of RAM in the memory map of the Macintosh (or almost like; video memory might exist on a NuBus™ video card, but it’s still RAM), QuickDraw can be told to draw into a part of memory that isn’t reserved for the video hardware, maybe into a part of your own application’s heap. When you tell QuickDraw to draw into a part of memory that’s not reserved for the video hardware, you can’t see any of the results. This is off-screen drawing. There are plenty of perfectly good reasons to do this, such as providing storage for a paint-style document or to smoothly animate an image, but the assumption here is that you have a perfectly good reason to do this so you’re more interested in the “how” of it instead of the “why” of it. If you need to know why, there are several books that cover off-screen drawing and the perfectly good reasons to do such a thing. A good place to start is Scott Knaster’s book, Macintosh Programming Secrets, referenced at the end of this Note.
This Note is divided into these major sections:
• The introduction is the part that you’re reading now.
• “The Building Blocks” provides an overview of the data structures that you need to tell Color QuickDraw to draw off screen.
• “Building the Blocks” discusses the construction and initialization of these data structures.
• “Playing With Blocks” shows an example of the use of these structures to draw off screen.
• “Put That Checkbook Away!” discusses some variations of these techniques to handle off-screen drawing for special cases.
• “The GWorld Factor” provides a brief overview of GWorlds, how to use them, and how they compare and contrast to the manual techniques that are described in most of this Note.
Those of you who aren’t quite sure whether to use GWorlds or the do-it-yourself techniques might want to skip ahead for a moment to “The GWorld Factor” just in case doing it yourself is a waste of time. In any case, it’s a good idea to read this whole Note because the concepts are mostly the same whether you’re using GWorlds or not. GWorlds just make the process a lot easier, and they let you take advantage of the 8•24 GC video card. But, we’re not in that section of the Note yet.
The Building Blocks
Before you can tell QuickDraw to draw off of the screen, you’ll need to build three major data structures: a CGrafPort, a PixMap, and a GDevice. You’ll also need a couple of tables that define the colors involved with drawing to and copying from the off-screen image: the color table and the inverse table. Of course, you’ll need the pixel image itself, which is often called the “pixel buffer” or the “image buffer” or the “off-screen buffer” or just “the buffer.” It’s always called the “pixel image” in this Note. It doesn’t necessarily buffer anything anyway.
The CGrafPort
A CGrafPort describes a drawing environment, and it’s the color version of the GrafPort structure that’s described on pages 147 through 155 in the QuickDraw chapter of Inside Macintosh Volume I. The drawing environment consists of, among other things, the size and location of the graphics pen, the foreground and background colors to use when something is drawn, the pattern to use, the region to clip all drawing to, and the portion of a pixel image that the CGrafPort logically exists in. Any initialized CGrafPort or GrafPort can be set as the current port through the _SetPort routine. The current port is a set of parameters that are implicitly passed to most QuickDraw routines.
The most important reason to build a new CGrafPort when you draw off screen rather than using an existing CGrafPort is so that switching between drawing to an off-screen graphics environment and drawing to one or more windows (each of which is an extended GrafPort or CGrafPort structure) on the screen is very easy. Some people use just one CGrafPort to share between on-screen and off-screen graphics environments, and switch their PixMap structures to switch between drawing on screen and drawing off screen. That does work, but if the off-screen and on-screen graphics environments have a different clipRgn, visRgn, pen characteristic, portRect, or any other characteristics that are different, then those must be switched at that time too. If you instead create a CGrafPort that’s dedicated to one graphics environment, then a simple call to _SetPort effectively switches all these things for you at once. That’s why every window on the screen comes with its own port. A simple call to _SetPort switches between the characteristics of each window even if each window has radically different drawing characteristics.
The CGrafPort data structure is more completely described in the “Color QuickDraw” chapter of Inside Macintosh Volume V, pages 49 through 52, and in the “Graphics Overview” chapter of Inside Macintosh Volume VI, pages 16-12 through 16-13.
The PixMap
A pixel image alone is just a formless blob of memory. Pixel maps, defined by the PixMap structure, describe pixel images, giving them a form and structure that’s suitable for Color QuickDraw to draw into them and copy from them. The PixMap structure tells you the dimensions and location in memory of the pixel image, its coordinate system, and the depth and format of the pixels. Pixel maps that describe indexed-color pixel images additionally describe the colors that are represented by the values of the pixels in the pixel image. This is done through the color table, also known as the color look-up table or CLUT. Color tables are attached to pixel maps through their pmTable field. Direct-color pixel images have pixel values that describe their own colors, and so color tables aren’t needed for those.
The PixMap structure is described in the “Color QuickDraw” chapter of Inside Macintosh Volume V, pages 52 through 55, and in the “Graphics Overview” chapter of Inside Macintosh Volume VI, pages 16-11 through 16-12. The concept of direct-color and indexed-color pixels is described in this same chapter on pages 16-16 through 16-18, and also in the “Color QuickDraw” chapter of the same volume on pages 17-4 through 17-10.
The GDevice
Graphics devices, defined by the GDevice structure, describe color environments. They’re the most misunderstood data structure when it comes to off-screen graphics environments for three major reasons: first, they’re not originally documented as being relevant to humans; second, they look as though they’re only for screens; and third, it looks as though color tables describe color environments. We can dispose of these myths here: graphics devices are documented as being useful to humanity in this Note at least; they’re critically important for both on-screen and off-screen drawing; and color tables describe the colors in pixel images, not color environments.
What’s all this about color environments? In theory, there are virtually three hundred trillion colors available with Color QuickDraw through the 48-bit RGBColor record. In reality, there are never this many colors available, and in fact there might be only two. Color QuickDraw maps the theoretical color that you specify to the pixel value of the closest available color in the current color environment. This can be done with a color table, but that’s not very efficient. Finding the closest available color to an RGBColor in a color table means searching the entire color table for that one closest color. If that’s done just once, then performance isn’t much of an issue, but if it’s done many times, the performance hit could be significant. A very bad case of this is _CopyBits, where every pixel value in the source image is converted to an RGBColor by looking it up in the color table of the source PixMap. If the color table of the destination PixMap had to be searched to find the closest available color for every pixel in the source PixMap, then the performance of even the most straightforward _CopyBits call could be a lot slower than it has to be.
To avoid this performance hit, the current GDevice provides an inverse table and a device type which are used to determine the available set of colors. Inverse tables are anticolor tables. Where color tables give you a color for a given pixel value, inverse tables give you a pixel value for a given color. Every conceivable color table has a corresponding conceivable inverse table, just as every positive real number has a corresponding negative real number, or every Mr. Spock has a corresponding Mr. Spock with a goatee. The device type specifies whether the color environment uses the indexed-color, fixed-color, or direct-color model. In the direct-color model, the inverse table is empty. Only the indexed-color and direct-color models are described in this Note.
When you specify a color in an indexed-color environment, Color QuickDraw takes the RGBColor specification and converts it into a value that can be used as an index into the inverse table of the current GDevice. To do this conversion, Color QuickDraw takes the top few significant bits of each color component and combines them into part of a 16-bit word, blue bits in the least significant bits, green bits right above it, and the red bits right above green bits. Any unused bits are in the most significant bits of the 16-bit word. The resulting 16-bit word is used as an index into the inverse table. The value in the inverse table at that index is the pixel value which best represents that color in the current color environment. The number of bits of each component that are used is determined by what’s called the “resolution” of the inverse table. Almost always, the resolution of an inverse table is four bits, meaning the most significant four bits of each component are used to form the index into the inverse table. Figure 1 shows how an RGBColor record is converted to an index into an inverse table when the inverse-table resolution is four.
Figure 1 Conversion of RGBColor Record to Inverse-Table Index
The same process is used when _CopyBits is called with an indexed-color destination. Each pixel in the source pixel image is converted to an RGBColor either by doing a table look-up of the source pixel map’s color table if the source pixel image uses indexed colors, or by expanding the pixel value to an RGBColor record if the source pixel image uses direct colors. The resulting RGBColor is then used to look up a pixel value in the inverse table of the current GDevice, and this pixel value is put into the destination pixel image.
If you specify a color in a direct-color environment, then the resulting RGBColor is converted to a direct pixel value by the processes that are shown on pages 17-6 through 17-9 of the “Color QuickDraw” chapter of Inside Macintosh Volume VI.
Usually, inverse-table look-up involves an extra step to find what are called “hidden colors” using proprietary information that’s stored at the end of the inverse table. With an inverse-table resolution of four, only 16 shades of any particular component can be distinguished, and that’s often not enough. An inverse table with a resolution of five is much larger, but it still only gives you 32 shades of any component. Hidden colors are looked up after the normal inverse-table look-up to give a much more accurate representation of the specified color in the current color environment than the inverse-table look-up alone can produce. Sometimes, most notably when the arithmetic transfer modes are used or if dithering is used, the hidden colors are ignored.
When a new color table is assigned to a PixMap or when its existing color table is modified, then a new corresponding inverse table should be generated for the GDevice that’ll be used when drawing into that environment. Normally, this happens automatically without you having to do any more than inform Color QuickDraw of the change. This is described in more detail in “Changing the Off-Screen Color Table” later in this Note.
Graphics devices are documented in the “Graphics Devices” chapter of Inside Macintosh Volume VI which supersedes the “Graphics Devices” chapter of Inside Macintosh Volume V. They’re also discussed in the “Graphics Overview” chapter of Inside Macintosh Volume VI, pages 16-13 through 16-14. The inverse-table mechanism is described in the “Color Manager” chapter of Inside Macintosh Volume V, pages 137 through 139.
All Together Now
There are a lot of different ways to put the three structures together, and this Note discusses the architecture that’s shown in Figure 2. This architecture is useful when you want a simple, atomic, off-screen graphics environment.
Figure 2 Relationships Between Structures for Off-Screen Drawing
Notice that there’s no way to get to the GDevice from the CGrafPort, nor is there a way to get to the CGrafPort from the GDevice, though the PixMap can be found through either one. Your application must keep track of both the CGrafPort and the GDevice.
Building the Blocks
As with just about any algorithm, there are many ways to put the different structures together that form an off-screen graphics environment. This section covers just one way to build the architecture that’s shown in Figure 2.
Building the CGrafPort
The CGrafPort structure is the easiest one to put together because the _OpenCPort routine initializes so many of the fields of the CGrafPort structure for you. It also allocates and initializes the structures that are attached to every CGrafPort, such as the visRgn, clipRgn, grafVars handle, and so forth. Most of these are initialized with values that are fine for general purposes, but the visRgn, clipRgn, and portRect fields should be set to the desired boundary rectangle of the off-screen graphics environment. What follows is an overview of each of the fields that you have to worry about when you’re setting up a CGrafPort for drawing off screen.
portPixMap handle to the off-screen PixMap. _OpenCPort initializes this field to a copy of the PixMap that’s attached to the gdPMap field of the current GDevice. An overview of setting up this PixMap for drawing off screen is given in “Building the PixMap” later in this Note.
portRect specifies the rectangular area of the associated pixel image that this CGrafPort controls. This field should be set to the desired rectangular area of the off-screen image because _OpenCPort doesn’t necessarily initialize it to this size. Usually, the top-left corner of this rectangle has the coordinates (0, 0), but not necessarily so.
visRgn handle to the region that specifies the visible area into which you can draw. _OpenCPort doesn’t necessarily initialize it to the size of the off-screen image, so it should be set to the same size and coordinates as the portRect and left at that. This field is more important for windows because parts of them can be hidden by other windows.
clipRgn handle to the region that specifies the logical area into which you can draw. _OpenCPort initializes it to cover the entire QuickDraw coordinate plane. It’s usually a good idea to set it to the same size and coordinates as the portRect to avoid problems if the clipRgn is scaled or translated, which causes its signed integer coordinates to overflow and turn it into an empty region. One of the most common cases of this occurs when a picture that’s created in this CGrafPort is drawn into a destination rectangle that’s any larger than or translated from the original picture frame. Everything in the picture, including the clip region, is scaled to fit the destination rectangle. If the clip region covers the entire QuickDraw coordinate plane, then its coordinates overflow their signed integer bounds, and the clip region becomes logically empty. The result is that nothing is drawn.
The CreateOffScreen routine in Listing 1 creates an off-screen graphics environment, given a boundary rectangle, pixel depth, and color table, and it returns a new off-screen CGrafPort and GDevice, along with an error code. The desired pixel depth in bits per pixel is given in the depth parameter. If the pixel depth is eight or less, then an indexed-color graphics environment is created and a color table is required in the colors parameter. If the pixel depth is 16 or 32 bits per pixel and 32-Bit QuickDraw is available, then a direct-color graphics environment is created and the colors parameter is ignored. If 32-Bit QuickDraw isn’t available, then a pixel depth of 16 or 32 bits per pixel results in CreateOffScreen doing nothing more than returning a parameter error. A description of CreateOffScreen is given following the listing.
MPW Pascal Listing 1
FUNCTION CreateOffScreen(
bounds: Rect; {Bounding rectangle of off-screen}
depth: Integer; {Desired number of bits per pixel in off-screen}
colors: CTabHandle; {Color table to assign to off-screen}
VAR retPort: CGrafPtr; {Returns a pointer to the new CGrafPort}
VAR retGDevice: GDHandle {Returns a handle to the new GDevice}
): OSErr;
CONST
kMaxRowBytes = $3FFE; {Maximum number of bytes in a row of pixels}
VAR
newPort: CGrafPtr; {Pointer to the new off-screen CGrafPort}
newPixMap: PixMapHandle; {Handle to the new off-screen PixMap}
newDevice: GDHandle; {Handle to the new off-screen GDevice}
qdVersion: LongInt; {Version of QuickDraw currently in use}
savedPort: GrafPtr; {Pointer to GrafPort used for save/restore}
savedState: SignedByte; {Saved state of color table handle}
bytesPerRow: Integer; {Number of bytes per row in the PixMap}
error: OSErr; {Returns error code}
BEGIN
(* Initialize a few things before we begin *)
newPort := NIL;
newPixMap := NIL;
newDevice := NIL;
error := noErr;
(* Save the color table’s current state and make sure it isn’t purgeable *)
IF colors <> NIL THEN
BEGIN
savedState := HGetState(Handle(colors));
HNoPurge(Handle(colors));
END;
(* Calculate the number of bytes per row in the off-screen PixMap *)
/* One Last Look Around The House Before We Go… */
if (error != noErr)
{
/* Some error occurred; dispose of everything we allocated */
if (newPixMap != nil)
{
DisposCTable( (**newPixMap).pmTable );
DisposPtr( (**newPixMap).baseAddr );
}
if (newDevice != nil)
{
DisposHandle( (Handle)(**newDevice).gdITable );
DisposHandle( (Handle)newDevice );
}
if (newPort != nil)
{
CloseCPort( newPort );
DisposPtr( (Ptr)newPort );
}
}
else
{
/* Everything’s OK; return refs to off-screen CGrafPort and GDevice */
*retPort = newPort;
*retGDevice = newDevice;
}
return error;
}
CreateOffScreen begins by making sure that the color table, if there is one, doesn’t get purged during the time that the off-screen graphics environment is created. Then, a sanity check is done for the given depth, bounds, and color table. The depth must be either 1, 2, 4, or 8 bits per pixel, or additionally 16 or 32 bits per pixel if 32-Bit QuickDraw is available. If these conditions aren’t satisfied, then it’s decided that there’s an error in the parameter list, and CreateOffScreen does nothing more. To determine whether 32-Bit QuickDraw is available or not, the _Gestalt routine is used. If _Gestalt returns a value that’s equal to or greater than the constant gestalt32BitQD, then 32-Bit QuickDraw is available and depths of 16 and 32 bits per pixel are supported. It’s not necessary to determine whether _Gestalt is available or not because it’s implemented as glue code in the Macintosh Programmer’s Workshop.
A check is then done to determine whether the number of bytes in each row of the off-screen pixel image is too much for QuickDraw to handle. Color QuickDraw can handle up to and including 16,382 ($3FFE) bytes in each row of any pixel image. If the required number of bytes per row exceeds this amount, then CreateOffScreen decides that there’s an error in the parameter list and does nothing more. The minimum number of bytes in a row that’s enough to cover the given boundary rectangle at the given pixel depth is calculated with the formula:
This formula multiplies the number of pixels across the PixMap by the pixel depth to get the number of bits, and then this is divided by eight to get the number of bytes. This division by eight looks very strange because the number of bytes per row must be even, so this formula takes advantage of integer division and multiplication to make the result come out even. This particular formula additionally makes sure that the number of bytes per row is a multiple of four. This helps optimize the performance of Color QuickDraw operations because it allows Color QuickDraw to refer to each row beginning on a long word boundary in memory.
The last sanity check is to make sure that a color table is given as a parameter if it’s needed. Indexed-color graphics environments need color tables, so if the given pixel depth is eight or less (which implies an indexed-color graphics environment) and the given color table is NIL, then CreateOffScreen decides that there’s an error in the parameter list and does nothing more. If the given pixel depth is 16 or 32 (which implies a direct-color graphics environment), then CreateOffScreen ignores the given color table.
If all the sanity checks succeed, then the off-screen CGrafPort is allocated using a call to _NewPtr, and then it’s initialized and opened as a CGrafPort by passing the resulting pointer to _OpenCPort. Because _OpenCPort makes the new CGrafPort the current port, the current port is first saved so that it can be restored as the current port when CreateOffScreen is done.
As mentioned above, the _OpenCPort doesn’t necessarily initialize the portRect, visRgn, and clipRgn of the new CGrafPort to the areas that are needed for any particular off-screen graphics environment. So, the given boundary rectangle is assigned to the portRect field, _RectRgn is called to make the visRgn equal to the given boundary rectangle, and _ClipRect is called to set the clipRgn so that it’s equal to the given boundary rectangle.
The PixMap in the portPixMap field needs to be initialized for off-screen drawing, and that’s handled by the SetUpPixMap routine that’s described and defined in “Building the PixMap” later in this Note. Similarly, the off-screen GDevice must be created and initialized. That’s handled by the CreateGDevice routine that’s described and defined in “Building the GDevice” later in this Note.
Once these things are done, CreateOffScreen returns a pointer to the off-screen CGrafPort in the retPort parameter and a handle to the off-screen GDevice in the retGDevice parameter. The way to use these references is described in “Playing With Blocks” later in this Note.
Building the PixMap
_OpenCPort initializes the portPixMap field of the CGrafPort it’s initializing with a copy of the PixMap of the current GDevice. When the CreateOffScreen routine described earlier executes, the current GDevice is unknown. So, all the fields of the PixMap that the new CGrafPort receives must be initialized so that it can be used for drawing off screen.* What follows is an overview of each of the PixMap fields and how they should be initialized for off-screen drawing.
baseAddr pointer to the off-screen pixel image. The off-screen pixel image is allocated as a nonrelocatable block in the heap. The size of this block of memory is calculated from the rowBytes field, described next, multiplied by the number of rows in the given boundary rectangle.
rowBytes number of bytes in each row of the pixel image. This value is calculated from the formula that’s given in the CreateOffScreen routine. The most significant bit of this field should be set so that Color QuickDraw knows that this is a PixMap rather than a BitMap. The maximum value, ignoring the most significant bit, is 16,382.
bounds defines the coordinate system and the dimensions of the pixel image. For most off-screen drawing, this should be a rectangle that covers the entire off-screen graphics environment.
pmVersion set of internally and externally defined flags. As of 32-Bit QuickDraw 1.2, only the baseAddr32 flag is defined externally. This flag is described in “Choosing Your Off-Screen Memory” later in this Note. For most off-screen drawing, this field is set to zero.
*This part of these routines really bothers me because it feels impure to initialize all the PixMap fields when _OpenCPort has initialized them already, just not in a way that’s any good for off-screen drawing. I tried creating the GDevice and PixMap first and then calling _OpenCPort so that it initializes its PixMap for off-screen drawing, but then you end up with two pixel maps and that makes this tougher to explain, or you have to dispose of one PixMap which seems worse than the method I’m using.
packType image compression scheme for pictures. The options for this field are discussed in the “Graphics Overview” chapter of Inside Macintosh Volume VI, pages 17-22 through 17-23. In this Note, image compression isn’t discussed so this field is set to zero.
packSize internally used field. This field is always set to zero.
hRes horizontal resolution of the pixel map. By default, the QuickDraw resolution is 72 dots per inch,which is the value this Note uses. This is a fixed-point field, so the actual value in this field is $00480000.
vRes vertical resolution of the pixel map. See the hRes description.
pixelType format of the pixels. In indexed-color pixel maps, this field holds zero. In direct-color pixel maps, this field holds the RGBDirect constant, which is equal to 16.
pixelSize number of bits in every pixel. For indexed-color pixels, this is 1, 2, 4, or 8 bits per pixel. For direct-color pixels, this is 16 or 32 bits per pixel.
cmpCount number of components in every pixel. In indexed-color pixel maps, this field is set to 1. In direct-color pixel maps, this field is set to 3. Sometimes it’s handy to set this field to 4 in 32-bit deep pixel maps when they’re being saved in a picture. See the “Color QuickDraw” chapter of Inside Macintosh Volume VI, page 17-23, for details about this.
cmpSize number of bits in each color component. In indexed-color pixel maps, this field is set to the same value that’s in the pixelSize field. In 16-bit deep direct pixel maps, this field is set to 5. In 32-bit deep direct pixel maps, this field is set to 8.
planeBytes not currently defined. This field is set to zero.
pmTable handle to the color table for indexed-color pixel maps. A method to create a color table is given in “About That Creation Thing . . .” later in this Note. In direct-color pixel maps, this field contains a handle to a dummy color table, and building one of these is shown in the SetUpPixMap routine in Listing 2.
pmReserved not currently defined. This field is set to zero.
The SetUpPixMap routine in Listing 2 initializes the PixMap that’s passed to it in the aPixMap parameter so that it can be used in an off-screen graphics environment. The depth, bounds, and color parameters are the same as the ones passed to the CreateOffScreen routine. The bytesPerRow parameter is the number of bytes in each row of the off-screen pixel image. A description of SetUpPixMap follows the listing.
MPW Pascal Listing 2
FUNCTION SetUpPixMap(
depth: Integer; {Desired number of bits/pixel in off-screen}
bound: Rect; {Bounding rectangle of off-screen}
colors: CTabHandle; {Color table to assign to off-screen}
bytesPerRow: Integer; {Number of bytes in each row of pixels}
aPixMap: PixMapHandle {Handle to the PixMap being initialized}
): OSErr;
CONST
kDefaultRes = $00480000; {Default resolution is 72 DPI; Fixed type}
VAR
newColors: CTabHandle; {Color table used for the off-screen PixMap}
offBaseAddr: Ptr; {Pointer to the off-screen pixel image}
error: OSErr; {Returns error code}
BEGIN
error := noErr;
newColors := NIL;
offBaseAddr := NIL;
(* Clone the clut if indexed color; allocate a dummy clut if direct color *)
(**aPixMap).pmTable = newColors; /* Handle to CLUT */
}
else
{
/* PixMap is direct */
(**aPixMap).pixelType = RGBDirect; /* Indicates direct */
(**aPixMap).cmpCount = 3; /* Have 3 components */
if (depth == 16)
(**aPixMap).cmpSize = 5; /* 5 bits/component */
else
(**aPixMap).cmpSize = 8; /* 8 bits/component */
(**newColors).ctSeed = 3 * (**aPixMap).cmpSize;
(**newColors).ctFlags = 0;
(**newColors).ctSize = 0;
(**aPixMap).pmTable = newColors;
}
}
else
error = MemError();
}
else
newColors = nil;
/* If no errors occurred, return a handle to the new off-screen PixMap */
if (error != noErr)
{
if (newColors != nil)
DisposCTable( newColors );
}
/* Return the error code */
return error;
}
SetUpPixMap begins by copying the given color table if an indexed-color graphics environment is being built, or allocating a dummy color table if a direct-color graphics environment is being built. A copy of the color table is made because this allows the given color table and the off-screen graphics environment’s color table to be manipulated independently without interfering with each other, and this lets the off-screen graphics environment routines manipulate the color table without needing to worry about whether the color table is a 'clut' resource or not. The dummy color table is made so that routines which assume that every PixMap has a color table won’t do something catastrophic if they find a NIL color table. The off-screen pixel image is then allocated as a nonrelocatable block in the application’s heap.
Some of the fields of a PixMap have to be initialized differently depending upon whether the indexed-color model or the direct-color model is being used. So, the fields that are the same regardless of the color model that’s being used are assigned first. Then the desired pixel depth is compared to 8. If the depth is less than or equal to 8, then the rest of the fields are initialized for the indexed-color model. Otherwise, the rest of the fields are initialized for the direct color model. In the case of the direct-color model, the dummy color table is initialized to have no CSpecArray entries and its ctSeed field is set to three times the component size. This dummy color table is then installed into the PixMap.
Once SetUpPixMap completes, the PixMap of the new CGrafPort is ready to hold an off-screen image. It’s not quite ready to be drawn into with Color QuickDraw though. To do that, the off-screen GDevice is still needed; the construction and initialization of the GDevice are covered in the next section.
Building the GDevice
The _OpenCPort routine automatically allocates and initializes a PixMap, and the SetUpPixMap routine reinitializes that existing PixMap. _OpenCPort doesn’t allocate nor initialize a GDevice, so one has to be created from scratch. Pages 21-20 through 21-21 of “The Graphics Devices Manager” chapter of Inside Macintosh Volume VI describe the _NewGDevice routine. This routine seems as though it’s the ticket to getting a GDevice for off-screen drawing, but it always allocates the new GDevice in the system heap. That’s not so good because if your program unexpectedly quits or if you just forget to dispose of the GDevice before you quit for real, the GDevice gets orphaned in the system heap. To prevent this from happening, _NewGDevice should be ignored and the off-screen GDevice should instead be allocated and initialized from scratch. What follows is a description of how each field of the GDevice structure should be initialized.
gdRefNum reference number of video driver. Off-screen graphics environments don’t need to have video drivers because there’s no video device associated with them, so this field is set to zero.
gdID used to identify specific GDevice structures from color-search procedures. This isn’t necessary for off-screen drawing, so this is normally set to zero.
gdType type of GDevice. This field is set to the constant clutType (equal to zero) for an indexed-color environment and set to the constant directType (equal to 2) for a direct-color environment.
gdITable handle to the inverse table. Initially, this field is set to an arbitrarily small handle. Later, the _MakeITable routine is used to resize and initialize this handle to a real inverse table.
gdResPref inverse-table resolution. When _MakeITable is called by QuickDraw, the value of this field is used as the inverse-table resolution. Almost all inverse tables have a resolution of 4. There are some cases when a inverse-table resolution of 5 is useful, particularly when the arithmetic transfer modes are used with _CopyBits. See “The GDevice” earlier in this Note.
gdSearchProc pointer to the color-search procedure. If a color-search procedure is needed, this field can be set later by calling the _AddSearch routine (see the “Color Manager” chapter of Inside Macintosh Volume V, pages 145 through 147). Usually, this field is just set to NIL and left at that.
gdCompProc pointer to the color-complement procedure. If a color-complement procedure is needed, this field can be set later by calling the _AddComp routine (see the “Color Manager” chapter of Inside Macintosh Volume V, pages 145 through 147). Usually, this field is set to NIL and left at that.
gdFlags flags indicating certain states of the GDevice. This field should initially be set to zeroes. After the GDevice has been built, these flags can be set with the _SetDeviceAttrs routine (see the “Graphics Devices Manager” chapter of Inside Macintosh Volume VI, pages 21-10 and 21-22).
gdPMap handle to a PixMap. A handle to the PixMap of the CGrafPort that was created earlier is put into this field.
gdRefCon miscellaneous data. _CalcCMask and _SeedCFill use this field as described on pages 71 through 72 of Inside Macintosh Volume V. Initially, this field is set to zero.
gdNextGD handle to next GDevice in the GDevice list. The system maintains a linked list of GDevice records in which there’s one GDevice for every screen, and the links are kept in this field. Off-screen GDevice structures should never be put into this list, so this field should be set to NIL.
gdRect rectangle of GDevice. Strictly speaking, this field is used only for screens, but it should be the same as the bounds rectangle of the off-screen PixMap.
gdMode current video mode. This field is used by video drivers to keep track of the current mode that the video device is in. For off-screen GDevice structures, this field should be set to -1.
gdCC… These four fields are used only with GDevice structures for screens. For off-screen GDevice structures, these fields should be set to zero.
gdReserved not currently defined. This field is set to zero.
The CreateGDevice routine shown below in Listing 3 allocates and initializes a GDevice structure. It takes the initialized off-screen PixMap in the basePixMap parameter and returns the initialized GDevice in the retGDevice parameter. If any error occurs, any memory that’s allocated is disposed of and the result code is returned as a function result.
MPW Pascal Listing 3
FUNCTION CreateGDevice(
basePixMap: PixMapHandle; {Handle to the PixMap to base GDevice on}
VAR retGDevice: GDHandle {Returns a handle to the new GDevice}
): OSErr;
CONST
kITabRes = 4; {Inverse-table resolution}
VAR
newDevice: GDHandle; {Handle to the new GDevice}
embryoITab: ITabHandle; {Handle to the embryonic inverse table}
CreateGDevice begins by allocating the GDevice structure and an embryonic form of the inverse table in the current heap. The inverse table is allocated as two zero bytes for now; it’ll be resized and initialized to be a real inverse table later in this routine. Then, each of the GDevice fields are initialized as described earlier.
After all the fields have been initialized, the gdFlags field is set through _SetDeviceAttribute. If the desired pixel depth is greater than 1, then the gdDevType bit is set. This indicates that the GDevice is for a color graphics environment. This bit should be set even if a gray-scale color table is used for this off-screen graphics environment. The noDriver bit is set because this is an off-screen GDevice and so there’s no associated video device driver.
Finally, the inverse table is resized and initialized by calling the _MakeITable routine. A handle to the two-byte embryonic inverse table that was created earlier in CreateGDevice is passed as a parameter, as is a handle to the off-screen color table and the preferred inverse-table resolution.
All Fall Down
Now that we have a way to create an off-screen graphics environment, there has to be a way to get rid of it too. The DisposeOffScreen routine shown in Listing 4 does this. The CreateOffScreen routine returns an off-screen graphics environment that’s represented by a CGrafPort and GDevice. The DisposeOffScreen routine takes the off-screen CGrafPort and GDevice and deallocates all the memory that’s associated with them including the CGrafPort and its dependent structures, the GDevice, the PixMap, the color table, and the inverse table.
MPW Pascal Listing 4
PROCEDURE DisposeOffScreen(
doomedPort: CGrafPtr; {Pointer to the CGrafPort we’re getting rid of}
doomedGDevice: GDHandle {Handle to the GDevice we’re getting rid of}
);
VAR
currPort: CGrafPtr; {Pointer to the current port}
currGDevice: GDHandle; {Handle to the current GDevice}
BEGIN
(* Check to see whether the doomed CGrafPort is the current port *)
GetPort(GrafPtr(currPort));
IF currPort = doomedPort THEN
BEGIN
(* It is; set current port to Window Manager CGrafPort *)
GetCWMgrPort(currPort);
SetPort(GrafPtr(currPort));
END;
(* Check to see whether the doomed GDevice is the current GDevice *)
currGDevice := GetGDevice;
IF currGDevice = doomedGDevice THEN
(* It is; set current GDevice to the main screen’s GDevice *)
SetGDevice(GetMainDevice);
(* Throw everything away *)
doomedGDevice^^.gdPMap := NIL;
DisposGDevice(doomedGDevice);
DisposPtr(doomedPort^.portPixMap^^.baseAddr);
IF doomedPort^.portPixMap^^.pmTable <> NIL THEN
DisposCTable(doomedPort^.portPixMap^^.pmTable);
CloseCPort(doomedPort);
DisposPtr(Ptr(doomedPort));
END;
MPW C Listing 4
void DisposeOffScreen(
CGrafPtr doomedPort, /* Pointer to the CGrafPort to be disposed of */
GDHandle doomedGDevice) /* Handle to the GDevice to be disposed of */
{
CGrafPtr currPort; /* Pointer to the current port */
GDHandle currGDevice; /* Handle to the current GDevice */
/* Check to see whether the doomed CGrafPort is the current port */
GetPort( (GrafPtr *)&currPort );
if (currPort == doomedPort)
{
/* It is; set current port to Window Manager CGrafPort */
GetCWMgrPort( &currPort );
SetPort( (GrafPtr)currPort );
}
/* Check to see whether the doomed GDevice is the current GDevice */
currGDevice = GetGDevice();
if (currGDevice == doomedGDevice)
/* It is; set current GDevice to the main screen’s GDevice */
One mildly tricky aspect of this is that we shouldn’t dispose of the current graphics environment. To prevent this, the current port is retrieved by a call to _GetPort. If it returns a pointer to the same port that DisposeOffScreen is disposing, then the current port is set to the Window Manager’s CGrafPort. That was an arbitrary choice, but it’s the most neutral. Similarly, the current GDevice is retrieved by a call to _GetGDevice. If it returns a handle to the same GDevice that DisposeOffScreen is disposing, then the current port is set to the main screen’s GDevice. Again, that’s an arbitrary, neutral choice.
The inverse table, GDevice, pixel image, and color table are disposed of. Before disposing of the color table, a check is first made to see whether it’s NIL. That’s because it’s reasonable, though not normal, for the PixMap not to have even a dummy color table if the direct-color model is being used. Then the CGrafPort is closed which deallocates all the pieces associated with the CGrafPort, including the PixMap. Once this is done, all the structures that were created by calling CreateOffScreen are deallocated.
Playing With Blocks
Now that these four routines with two entry points can create and dispose of off-screen graphics environments, how are they used? There are several phases to using an off-screen graphics environment: creating it, drawing into it, switching between it and other off-screen and on-screen graphics environments, copying images to and from it, and disposing of it. Listing 5 shows a routine called ExerciseOffScreen which is a very basic example of all of these phases.
MPW Pascal Listing 5
PROCEDURE ExerciseOffScreen;
CONST
kOffDepth = 8; {Number of bits per pixel in off-screen environment}
rGrayClut = 1600; {Resource ID of gray-scale clut}
rColorClut = 1601; {Resource ID of full-color clut}
VAR
grayPort: CGrafPtr; {Graphics environment for gray off screen}
grayDevice: GDHandle; {Color environment for gray off screen}
colorPort: CGrafPtr; {Graphics environment for color off screen}
colorDevice: GDHandle; {Color environment for color off screen}
savedPort: GrafPtr; {Pointer to the saved graphics environment}
savedDevice: GDHandle; {Handle to the saved color environment}
offColors: CTabHandle; {Colors for off-screen environments}
offRect: Rect; {Rectangle of off-screen environments}
circleRect: Rect; {Rectangles for circle-drawing}
count: Integer; {Generic counter}
aColor: RGBColor; {Color used for drawing off screen}
error: OSErr; {Error return from off-screen creation}
BEGIN
(* Set up the rectangle for the off-screen graphics environments *)
SetRect(offRect, 0, 0, 256, 256);
(* Get the color table for the gray off-screen graphics environment *)
offColors := GetCTable(rGrayClut);
(* Create the gray off-screen graphics environment *)
/* Dispose of the off-screen graphics environments */
DisposeOffScreen( grayPort, grayDevice );
DisposeOffScreen( colorPort, colorDevice );
}
}
}
Two off-screen graphics environments are created in the same way. A rectangle that’s 256 pixels wide by 256 pixels high and with its top-left coordinate at (0, 0) is created in the offRect local variable. 'clut' resources are loaded from the application’s resource fork to use as the color tables of the two off-screen graphics environments; a gray-scale 'clut' in the first case and a full-color 'clut' in the second case. Then, CreateOffScreen is called with the rectangle, color table, and a hard-coded pixel depth of eight bits per pixel.
If CreateOffScreen returns noErr in both cases, then the current graphics environment is saved so that it can be restored later. Graphics environments consist of the current port and the current GDevice. The current GrafPort or CGrafPort is saved with _GetPort. The current GDevice is saved with _GetGDevice.
The gray-scale off-screen graphics environment is set as the current graphics environment by calling _SetPort with its CGrafPort and calling _SetGDevice with its GDevice. A vertical gray ramp is drawn into this graphics environment with the usual set of QuickDraw calls. This graphics environment’s pixel image is then copied to the full-color off-screen graphics environment with dithering and colorization with green (dithering requires 32-Bit QuickDraw and consistent colorization requires system software version 7.0; both of these features are described in Konstantin Othmer’s article “QuickDraw’s CopyBits Procedure: Better Than Ever in System 7.0” in Issue 6 of develop). Before this copy happens, the full-color off-screen graphics environment must be set as the current one. Once this is done, _CopyBits can properly map colors from the gray-scale off-screen graphics environment to the full-color one which gets a green ramp image.
Red, green, and blue concentric circles are drawn into the full-color off-screen graphics environment over the green ramp. This image is then copied to the graphics environment that was the current one when ExerciseOffScreen was called. To do this, the saved graphics environment is set as the current one by what should now be the familiar calls to _SetPort and _SetGDevice. The off-screen image is then copied to the saved graphics environment with _CopyBits.
Finally, the two off-screen graphics environments are disposed of by calling the DisposeOffScreen routine that’s defined in the section “All Fall Down” earlier in this Note.
Put That Checkbook Away!
The previous section covered the basics of creating and using off-screen graphics environments. This is good enough for many, if not most, needs of off-screen drawing. But there are variations to creating and maintaining an off-screen graphics environment for specific cases. This section discusses a few of the more common cases.
About That Creation Thing . . .
The CreateOffScreen routine, defined in Listing 1, takes three pieces of information: the boundary rectangle, the desired pixel depth, and the desired color table. But there’s much more to these pieces than ExerciseOffScreen shows. This section describes these pieces in more detail.
The first parameter to CreateOffScreen is a rectangle which determines the size and coordinate system of the off-screen graphics environment. Usually, the top-left corner of the rectangle has the coordinate (0, 0) because it’s usually easiest to draw everything using coordinates that can also be thought of as the horizontal and vertical distance in pixels from the top-left corner of the graphics environment. But in some cases, it’s more convenient to have the (0, 0) coordinate somewhere else, and passing CreateOffScreen a rectangle with a nonzero coordinate in the top-left corner is an easy way to do this. The coordinate system can be translated after the off-screen graphics environment is created by using the _SetOrigin routine that’s described on pages 153 through 155 of Inside Macintosh Volume I.
Warning: As Inside Macintosh Volume I, page 154, notes, the clip region of the port “sticks” to the coordinate system when you call _SetOrigin. If _SetOrigin offsets the coordinate system by a large amount, then the clip region might be moved completely outside of the port’s drawing area, and nothing can be drawn into that port. After calling _SetOrigin, you should set the clip region so that you can continue drawing into the port.
The number of bits per pixel implies the maximum number of available colors in a graphics environment, at least roughly speaking. The relationship between the number of bits per pixel and the number of available colors is discussed in the “Graphics Overview” chapter of Inside Macintosh Volume VI, pages 16-8 through 16-9.
If an indexed-color graphics environment is being made, then a color table must be passed to CreateOffScreen. In ExerciseOffScreen, the color table is retrieved from a 'clut' resource that’s in the application’s resource fork with a call to _GetCTable. Because CreateOffScreen clones this color table, this 'clut' resource can be purgeable so that it can be thrown out if its memory is needed for other purposes. _GetCTable can also be passed some special constants that tell it to allocate various system color tables that can also be passed to CreateOffScreen. These special constants are described on page 17-18 of the “Color QuickDraw” chapter of Inside Macintosh Volume VI. _GetCTable allocates memory for these system color tables, so they should be disposed of after you’re done with them.
A color table could also be built from scratch by allocating it with a call to _NewHandle and then initializing it by hand. The ColorTable structure is documented on pages 48 through 49 of Inside Macintosh Volume V. Here’s what each of the fields should be set to:
ctSeed identification value. This is an arbitrary value that should be changed any time the contents of the color table change so that the inverse table can be kept current. When Color QuickDraw draws anything, it compares the ctSeed of the color table of the PixMap of the current GDevice against the iTabSeed field of the inverse table of the current GDevice. If they’re the same, then Color QuickDraw uses colors according to that inverse table. If they’re different, then Color QuickDraw first rebuilds the inverse table according to the new color table’s contents and its iTabSeed is set to the value of the new color table’s ctSeed; then the rebuilt inverse table is used.
When _CopyBits is called with the srcCopy transfer mode, the ctSeed fields of the source and destination pixel maps are compared. If they’re the same, then _CopyBits simply transfers the source pixels to the destination with no mapping of colors. If they’re different, then _CopyBits checks each entry of the color tables to determine whether they have the same colors for the same pixel values. If they do, then _CopyBits again simply transfers the source pixels to the destination with no mapping of colors. If they don’t, then _CopyBits maps colors in the source PixMap to the colors in the current graphics environment according to the inverse table of the current GDevice. The ctSeed field of a color table should be changed whenever its contents are changed so that _CopyBits doesn’t make the wrong assumptions about the equality of the source and destination color tables.
You can get a seed value for a new color table by assigning to it the result of the _GetCTSeed routine, documented in the “Color Manager” chapter of Inside Macintosh Volume V, page 143. If the contents of an existing color table are changed, then it should be passed to the _CTabChanged routine which assigns a new value to its ctSeed field. If the _CTabChanged routine isn’t available (it’s available with 32-Bit QuickDraw and is included with the system beginning with system software version 7.0), then the ctSeed field should be given a new value with another call to _GetCTSeed.
ctFlags indicates the Boolean characteristics of a color table. If the most significant bit of ctFlags is clear, then the value field of each ColorSpec entry in the ctTable array is interpreted as the pixel value for the color that’s specified in the rgb field in the same ColorSpec entry. You can build a color table with nonconsecutive pixel values this way. If this bit is set, then all the value fields in the color table are ignored and the index of each ColorSpec record in the ctTable array is that record’s pixel value. It’s your choice whether to clear this bit and set the value fields or set this bit and ignore the value fields; traditionally this bit is clear for off-screen color tables.
If the next most significant bit of ctFlags is set, then the value field of each ColorSpec record in the ctTable array is used by _CopyBits as an index into the color palette that’s attached to the destination window, and the rgb field is ignored. This is documented in the “Palette Manager” chapter of Inside Macintosh Volume VI, page 20-17.
The other bits are reserved for future use. If you create a color table from scratch, these other bits must be set to zero. If you use a color table that’s generated by the system, then these bits must be preserved.
ctSize the number of color table entries minus 1. Normally, this field is set to 1, 3, 15, or 255 for 1-, 2-, 4-, and 8-bits per pixel, respectively. In special cases, it’s reasonable to have less than the maximum number of entries for the pixel depth. For example, a color table for an 8-bit per pixel graphics environment could have just 150 entries, in which case the ctSize field should hold 149. For this case, it’s still important to allocate as much space in the color table for the maximum number of entries for a pixel depth and clear the entries you’re not using to zero because some parts of Color QuickDraw assume the size of a color table based on the pixel depth.
ctTable array of colors and pixel values. This table defines all the available colors in the color table and their pixel values. The value field of each ColorSpec record indicates that color’s pixel value if the most significant bit of ctFlags is clear. It’s ignored if the most significant bit of ctFlags is set. The value field is used as an index into a palette if the next most significant bit of ctFlags is set, in which case the rgb field is ignored. See the discussion of the ctFlags field earlier in this Note for more details.
Warning: Color QuickDraw’s text-drawing routines assume that the color table of the destination graphics environment has the maximum number of colors for the pixel depth of the graphics environment, and that white is the first entry in the color table and black is the last entry. If these conditions aren’t satisfied, then the resulting image is unpredictable.
The code fragment in Listing 6 shows how to allocate a 256-entry color table from scratch. Color tables have a variable size, so the _NewHandle call has to calculate the size of the ColorTable record plus the maximum number of color table entries for the pixel depth multiplied by the size of a ColorSpec record. kNumColors - 1 is used in the calculation because the size of the ColorTable record includes the size of one ColorSpec entry in most development environments.
MPW Pascal Listing 6
CONST
kNumColors = 256; {Number of color table entries}
VAR
newColors: CTabHandle; {Handle to the new color table}
After you create an off-screen graphics environment with certain dimensions, you might later want to change its size, depth, or color table without creating a completely new graphics environment from scratch and without needing to redraw the existing image. The UpdateOffScreen routine in Listing 7 shows just one way to do this. It takes the same parameters that CreateOffScreen (defined in Listing 1) does, but instead of creating a new CGrafPort and GDevice, it alters the ones that you pass through the updPort and updGDevice parameters. If the newBounds parameter specifies an empty rectangle, then the existing boundary rectangle for the off-screen graphics environment is used. Similarly, if newDepth is zero, then the existing depth is used; and if the newColors parameter is NIL, then the existing color table is used. UpdateOffScreen alters the given CGrafPort and GDevice to the new settings, but it completely replaces the PixMap. After all the alterations are made, the old PixMap’s image is copied to the new PixMap’s image, and then the old PixMap and its image are disposed.
MPW Pascal Listing 7
FUNCTION UpdateOffScreen(
newBounds: Rect; {New bounding rectangle of off-screen}
newDepth: Integer; {New number of bits per pixel in off-screen}
newColors: CTabHandle; {New color table to assign to off-screen}
updPort: CGrafPtr; {Returns a pointer to the updated CGrafPort}
updGDevice: GDHandle {Returns a handle to the updated GDevice}
): OSErr;
CONST
kMaxRowBytes = $3FFE; {Maximum number of bytes per row of pixels}
VAR
newPixMap: PixMapHandle; {Handle to the new off-screen PixMap}
oldPixMap: PixMapHandle; {Handle to the old off-screen PixMap}
bounds: Rect; {Boundary rectangle of off-screen}
depth: Integer; {Depth of the off-screen PixMap}
bytesPerRow: Integer; {Number of bytes per row in the PixMap}
colors: CTabHandle; {Colors for the off-screen PixMap}
savedFore: RGBColor; {Saved foreground color}
savedBack: RGBColor; {Saved background color}
aColor: RGBColor; {Used to set foreground and background color}
qdVersion: LongInt; {Version of QuickDraw currently in use}
savedPort: GrafPtr; {Pointer to GrafPort used for save/restore}
savedDevice: GDHandle; {Handle to GDevice used for save/restore}
savedState: SignedByte; {Saved state of color table handle}
error: OSErr; {Returns error code}
BEGIN
(* Initialize a few things before we begin *)
newPixMap := NIL;
error := noErr;
(* Keep the old bounds rectangle, or get the new one *)
IF EmptyRect(newBounds) THEN
bounds := updPort^.portRect
ELSE
bounds := newBounds;
(* Keep the old depth, or get the old one *)
IF newDepth = 0 THEN
depth := updPort^.portPixMap^^.pixelSize
ELSE
depth := newDepth;
(* Get the old clut, or save new clut’s state and make it nonpurgeable *)
IF newColors = NIL THEN
colors := updPort^.portPixMap^^.pmTable
ELSE
BEGIN
savedState := HGetState(Handle(newColors));
HNoPurge(Handle(newColors));
colors := newColors;
END;
(* Calculate the number of bytes per row in the off-screen PixMap *)
/* Get rid of the old PixMap and its dependents */
DisposPtr( (**oldPixMap).baseAddr );
DisposeCTable( (**oldPixMap).pmTable ) ;
DisposHandle( (Handle)oldPixMap );
}
}
else
error = MemError();
}
/* Restore the given state of the color table */
if (colors != nil)
HSetState( (Handle)colors, savedState );
/* One Last Look Around The House Before We Go… */
if (error != noErr)
{
/* Some error occurred; dispose of everything we allocated */
if (newPixMap != nil)
{
if ((**newPixMap).pmTable)
DisposCTable( (**newPixMap).pmTable );
if ((**newPixMap).baseAddr)
DisposPtr ( (**newPixMap).baseAddr );
DisposHandle( (Handle)newPixMap );
}
}
return error;
}
UpdateOffScreen begins by checking the boundary rectangle, depth, or color table for emptiness, zero, or NIL, respectively. If any these satisfy that condition, then the existing characteristic is used. Next, the same sanity check that CreateOffScreen uses is done. If this sanity check succeeds, then a new PixMap is allocated, and then it’s initialized by the SetUpPixMap routine that’s given in Listing 2 which gives the new PixMap a new pixel image and its own copy of the color table. This new PixMap is installed into the CGrafPort after saving the reference to the old PixMap. Then, the portRect, visRgn, and clipRgn of the CGrafPort are set to the new boundary rectangle, as is the gdRect of the GDevice. The gdType of the GDevice is set either for the indexed-color or direct-color model, the gdPMap is set to the new PixMap, and the device attributes are set according to the pixel depth. Details about the settings for the CGrafPort and GDevice are in “Building the CGrafPort” and “Building the GDevice,” respectively, earlier in this Note.
At this point, the off-screen graphics environment is ready with its new characteristics, but it has garbage for an image because nothing has been drawn into it yet. The old PixMap, pixel image, and color table are still around, so _CopyBits transfers the old image into the altered graphics environment. _CopyBits handles the mapping from the old image’s characteristics to the new characteristics, so the altered graphics environment gets the best possible representation of the old image according to its new characteristics.
Changing the Off-Screen Color Table
Sometimes, it’s useful to change some or all of the colors in an off-screen color table, or to replace the off-screen color table with another one, so that the existing image in an indexed-color graphics environment appears with new colors. For example, if you had an off-screen image of a blue car and wanted to see what it looked like in green, you could change all of the shades of blue in the off-screen color table to green, and then _CopyBits the image to the screen. Notice that this is different from calling the UpdateOffScreen routine in the previous section with a different color table. That routine tries to reproduce the colors from the original image as best it can in the new set of colors. This section discusses the case in which you want the image’s colors to change.
The most obvious part of doing this is simply to get the color table from the off-screen pixel map’s pmTable field and modify the entries, or to dispose of the off-screen graphics environment’s current color table and assign the new one to it. There’s one more step to complete the process though. The discussion about GDevice records in “The Building Blocks” in this Note discusses inverse tables and how they go hand-in-hand with color tables. If you alter or replace the color table, you have to make sure that the inverse table of the off-screen drawing environment is rebuilt according to the new colors because Color QuickDraw uses that inverse table to know what pixel values to use for the specified color. You don’t have to rebuild the inverse table explicitly as long as you tell Color QuickDraw that the color table changed. To do this, all you have to do is make sure that the ctSeed of the changed or altered color table is set to a new value. And to do this, you can simply call _CTabChanged, which is documented on page 17-26 of the “Color QuickDraw” chapter of Inside Macintosh Volume VI. _CTabChanged is available beginning with 32-Bit QuickDraw and it’s available in system software version 7.0. If this routine isn’t available, then you can still tell Color QuickDraw that the color table has been changed by calling _GetCTSeed and assigning its result directly to your new color table’s ctSeed field.
The next time you draw into this off-screen drawing environment, Color QuickDraw checks the ctSeed of the environment’s color table against the iTabSeed of the inverse table of the environment’s GDevice. Because you changed the ctSeed of the color table either through _CTabChanged or _GetCTSeed, these two seeds are different so Color QuickDraw automatically rebuilds the inverse table of the current GDevice and then it copies the ctSeed of the color table to the iTabSeed of the rebuilt inverse table. Then drawing continues normally.
Follow That Screen!
One common need of off-screen graphics environments is that they have a depth and color table that matches a screen. The CreateOffScreen routine requires a color table for indexed-color environments, and a pixel depth. Because there can be more than one screen attached to a Macintosh system, you have to decide which screen’s depth and color table you should use. Typically, the depth and color table of the deepest screen that contains the area that you’re interested in (probably the area of a window) is used. Another option is to use the depth and color table of the screen that has the largest area of intersection with the area that you’re interested in. To find the depth and color table of the screen on which you want to base an off-screen graphics environment, you must use the list of graphics devices for all screens which is maintained by the system. Every GDevice record for a screen has a handle to that screen’s PixMap, and you can find the screen’s depth and color table there.
Listing 8 shows a routine called CreateScreenOffScreen which creates an off-screen graphics environment that has the depth and color table of a selected screen. The first parameter, bounds, specifies the rectangular part of the screen area in which you’re interested in global coordinates. The screenOption parameter specifies how you want the screen to be chosen. If you pass kDeepestScreen in this parameter, CreateScreenOffScreen creates the new off-screen graphics environment with the depth and color table of the deepest screen that intersects the bounds rectangle. If you instead pass kLargestScreenArea, then the new off-screen graphics environment is created with the depth and color table of the screen with the largest area of intersection with the bounds rectangle.
MPW Pascal Listing 8
TYPE
ScreenOpt = (kDeepestScreen, kLargestAreaScreen);
FUNCTION CreateScreenOffScreen(
bounds: Rect; {Global rectangle of part of screen to save}
screenOption: ScreenOpt; {Use deepest or largest intersection area screen?}
VAR retPort: CGrafPtr; {Returns a pointer to the new CGrafPort}
VAR retGDevice: GDHandle {Returns a handle to the new GDevice}
): OSErr;
VAR
baseGDevice: GDHandle; {GDevice to base off-screen on}
aGDevice: GDHandle; {Handle to each GDevice in the GDevice list}
basePixMap: PixMapHandle; {baseGDevice’s PixMap}
maxArea: LongInt; {Largest intersection area found}
area: LongInt; {Area of rectangle of intersection}
commonRect: Rect; {Rectangle of intersection}
normalBounds: Rect; {bounds rectangle normalized to (0, 0)}
error: Integer; {Error code}
BEGIN
error := noErr;
(* Different screen options require different algorithms *)
IF screenOption = kDeepestScreen THEN
(* Graphics Devices Manager tells us the deepest intersecting screen *)
baseGDevice := GetMaxDevice(bounds)
ELSE IF screenOption = kLargestAreaScreen THEN
BEGIN
(* Get a handle to the first GDevice in the GDevice list *)
aGDevice := GetDeviceList;
(* Keep looping until all GDevices have been checked *)
maxArea := 0;
baseGDevice := NIL;
WHILE aGDevice <> NIL DO
BEGIN
(* Check to see whether screen rectangle and bounds intersect *)
IF SectRect(aGDevice^^.gdRect, bounds, commonRect) THEN
BEGIN
(* Calculate area of intersection *)
area := LongInt(commonRect.bottom - commonRect.top) *
LongInt(commonRect.right - commonRect.left);
(* Keep track of largest area of intersection so far *)
IF area > maxArea THEN
BEGIN
maxArea := area;
baseGDevice := aGDevice;
END;
END;
(* Go to the next GDevice in the GDevice list *)
aGDevice := GetNextDevice(aGDevice);
END;
END
ELSE
error := paramErr;
(* If no screens intersect the bounds, baseDevice is NIL *)
Finding the deepest screen that intersects an on-screen area is trivially easy because there’s a Graphics Devices Manager routine that finds it called _GetMaxDevice which is documented on page 21-22 of the “Graphics Devices Manager” chapter of Inside Macintosh Volume VI. The rectangle in global coordinates of the screen area you’re interested in is passed to _GetMaxDevice, and it returns a handle to the deepest screen that intersects that area, even if the area of intersection is as small as one pixel. If no screens intersect that area, then _GetMaxDevice returns NIL.
Finding the GDevice of the screen that has the maximum area of intersection with the screen area you’re interested in isn’t quite so easy because there’s no single Graphics Devices Manager routine to find this GDevice; you have to search the GDevice list yourself. You can get a handle to the first GDevice in the list by calling _GetDeviceList, and you can get a handle to each successive GDevice by calling _GetNextDevice. _GetDeviceList is documented on pages 21-21 through 21-22 of the “Graphics Devices Manager” chapter of Inside Macintosh Volume VI, and _GetNextDevice is documented on page 21-22 of the same chapter. For each GDevice in the list, the area of intersection between the bounds and the gdRect of the GDevice is calculated. If the calculated area is the largest area of intersection found so far, then that area and the GDevice of that screen are remembered.
Once a winning GDevice has been chosen, either by being the deepest intersecting GDevice or the GDevice with the largest intersecting area, then CreateOffScreen routine is called with the pixel depth and color table of the PixMap of the GDevice, and the bounds rectangle normalized so that its top-left coordinate has the coordinates (0, 0). CreateOffScreen returns with the new off-screen graphics environment, and CreateScreenOffScreen returns this to the caller.
Choosing Your Off-Screen Memory
The CreateOffScreen routine in Listing 1 creates an off-screen graphics environment with its pixel image allocated as a nonrelocatable block in the application’s heap. But this isn’t the only way that the pixel image can be allocated. Pixel images can be big, and big blocks of nonrelocatable memory in your heap can be expensive in terms of performance, and they can cause a bad case of heap fragmentation. Why not put the pixel image in a relocatable block of memory instead? If there isn’t much free memory in your heap and if MultiFinder or system software version 7.0 is running, there’s memory that’s not being used by any open applications, called temporary memory (formerly called MultiFinder temporary memory). Why not use this area of memory for the pixel image? Some people have NuBus cards with plenty of memory on them. Why not move the pixel image out of the heaps altogether and instead use NuBus memory for the pixel image? All of these things can be done with simple modifications to what’s been discussed in this Note, and these modifications are discussed in the next few paragraphs.
How can pixel images be relocatable? After all, pixel images are referred to only by the baseAddr field of a PixMap, and the baseAddr is a pointer, not a handle. It’s true that while QuickDraw is being used to draw into a graphics environment, the pixel image had better not move or else QuickDraw will start drawing over the area of memory that the pixel image used to be rather than where it is. But if QuickDraw isn’t doing anything with the graphics environment, then it doesn’t care what happens to the pixel image as long as the baseAddr points to it once QuickDraw starts drawing into the graphics environment. This implies a strategy: allocate the pixel image as a relocatable block and let it float in the heap; when QuickDraw is about to to draw into the graphics environment or to copy from it, lock the pixel image and copy its master pointer into the baseAddr field of the PixMap; when the drawing or copying is finished, unlock the pixel image. There are many ways to implement this, and Listing 9 shows a code fragment for one very simple method.
MPW Pascal Listing 9
...
(* Allocate the pixel image; use long multiplication to avoid overflow *)
Listing 9 starts with a code fragment from the SetUpPixMap routine that’s modified so that it allocates a new handle for the off-screen pixel image instead of a new pointer. This handle is saved in the baseAddr field for now. When you’re about to draw into the off-screen graphics environment or to copy from it, the LockOffScreen routine in Listing 9 should be called with a pointer to the off-screen graphics environment’s CGrafPort as the parameter. It takes the handle to the pixel image from the baseAddr field of the off-screen graphics environment’s PixMap and passes it to _HLock which makes sure the pixel image can’t move in the heap. Then, the pixel image’s handle is dereferenced to get the master pointer to the pixel image, and this master pointer is copied into the baseAddr field. Now, QuickDraw can draw into or copy from the off-screen graphics environment.
When you’re finished drawing into the off-screen graphics environment, the pixel image should be unlocked, and the UnlockOffScreen routine in Listing 9 does this. The baseAddr field of the PixMap holds the pixel image’s master pointer, so this is passed to _RecoverHandle to get the pixel image’s handle. This handle is passed to _HUnlock to let the pixel image float in the heap again, and then this handle is saved in the baseAddr field.
One potentially useful addition to the LockOffScreen routine would be a call to _MoveHHi just before the call to _HLock. This helps reduce heap fragmentation while the pixel image is locked by moving it up as high in the heap as possible before locking it, allowing the other relocatable blocks to move without tripping over it. You have to be careful with _MoveHHi though because it not only moves the handle as high in the heap as possible, it moves other relocatable blocks out of the top of the heap to make room for the handle. This could involve moving huge amounts of memory, and it’s not unusual for _MoveHHi to take several seconds to do this.
How do you make an off-screen graphics environment that uses temporary memory for the pixel image? Temporary memory is allocated as handles, so there’s almost no difference between using temporary memory and using relocatable blocks in your own heap in the way that Listing 9 shows. All you have to do is replace the calls to _NewHandle, _HLock, and _HUnlock with calls to _TempNewHandle, _TempHLock, and _TempHUnlock. If temporary memory handles are real, then you don’t even have to replace the _HLock and _HUnlock calls—they work properly with temporary memory handles that are real.You can tell whether temporary memory handles are real or not by calling _Gestalt with the gestaltOSAttr selector. If the gestaltRealTempMemory bit is set, then all temporary memory handles are real. See the sections “About Temporary Memory” and “Using Temporary Memory” of Inside Macintosh Volume VI, pages 28-33 through 28-40.
How do you make an off-screen graphics environment that stores the pixel image on a NuBus memory card? The Macintosh Memory Manager doesn’t keep track of heaps on NuBus memory cards so it can’t be used to allocate memory on those cards, but if applications can use that card’s memory at will, then an application can set up the off-screen graphics environment with its pixel image in the NuBus card’s memory simply by setting the address of the card’s memory in the baseAddr field of the off-screen graphics environment’s PixMap instead of allocating anything.
If your NuBus memory card doesn’t require 32-bit addressing mode to access its memory, then setting the baseAddr to the address of the NuBus card’s memory is all you have to do. Some NuBus memory cards require its memory to be accessed in 32-bit addressing mode. Without 32-Bit QuickDraw, these memory cards can’t be used for storing the pixel image of an off-screen graphics environment because Color QuickDraw without 32-Bit QuickDraw always reads and writes pixel images in 24-bit addressing mode regardless of whether the pixel image is in main memory, on a NuBus video card, or on a NuBus memory card. With 32-Bit QuickDraw, Color QuickDraw automatically switches to 32-bit addressing mode before reading or writing a pixel image that’s on a video card. It won’t know to switch to 32-bit addressing mode if your off-screen graphics environment uses a pixel image on a NuBus memory card that’s not a video card, but you can tell it to make this switch by setting bit 2 of the pmVersion field of the PixMap for the off-screen graphics environment. This is normally done by logically ORing the pmVersion field with the predefined constant baseAddr32. See “About 32-Bit Addressing” in Issue 6 of develop, page 36, for more details about how QuickDraw handles addressing modes.
The GWorld Factor
In May 1989, 32-Bit QuickDraw was introduced as an extension to the system. While it had a lot of new features, the GWorld mechanism was the one that made the big news. GWorlds are off-screen graphics environments that you can have the system put together in one call. There’s no need for routines like CreateOffScreen, SetUpPixMap, or CreateGDevice—all of the off-screen graphics environment is set up with _NewGWorld. You can change most of its characteristics with _UpdateGWorld, set the current off-screen graphics environment with _SetGWorld, and get rid of the off-screen graphics environment with _DisposeGWorld. All the GWorld routines are described in the “Graphics Devices Manager” chapter of Inside Macintosh Volume VI. As an example, Listing 10 shows the same routine as the ExerciseOffScreen routine that’s shown in Listing 5, but Listing 10 uses GWorlds rather than the do-it-yourself routines that are defined in this Note.
MPW Pascal Listing 10
PROCEDURE ExerciseOffScreen;
CONST
kOffDepth = 8; {Number of bits per pixel in off-screen environment}
rGrayClut = 1600; {Resource ID of gray-scale clut}
rColorClut = 1601; {Resource ID of full-color clut}
VAR
grayPort: GWorldPtr; {Graphics environment for gray off screen}
colorPort: GWorldPtr; {Graphics environment for color off screen}
savedPort: GrafPtr; {Pointer to the saved graphics environment}
savedDevice: GDHandle; {Handle to the saved color environment}
offColors: CTabHandle; {Colors for off-screen environments}
offRect: Rect; {Rectangle of off-screen environments}
circleRect: Rect; {Rectangles for circle-drawing}
count: Integer; {Generic counter}
aColor: RGBColor; {Color used for drawing off-screen}
error: OSErr; {Error return from off-screen creation}
BEGIN
(* Set up the rectangle for the off-screen graphics environments *)
SetRect(offRect, 0, 0, 256, 256);
(* Get the color table for the gray off-screen graphics environment *)
offColors := GetCTable(rGrayClut);
(* Create the gray off-screen graphics environment *)
/* Copy the color off-screen environment to the current port */
SetGWorld( savedPort, savedDevice );
CopyBits( &((GrafPtr)colorPort)->portBits,
&((GrafPtr)savedPort)->portBits,
&colorPort->portRect,
&savedPort->portRect,
srcCopy, nil );
/* Dispose of the off-screen graphics environments */
DisposeGWorld( grayPort );
DisposeGWorld( colorPort );
}
}
}
_NewGWorld creates an off-screen graphics environment by creating a CGrafPort, PixMap, and GDevice—the same structures that you normally put together when you make an off-screen graphics environment yourself. In this aspect, and in fact in most aspects, there’s nothing magical about GWorlds. Do GWorlds make the CreateOffScreen, DisposeOffScreen, and their dependents useless? That depends on what your needs are. What follows are a few issues about off-screen drawing and how that determines whether you use your own routines, such as CreateOffScreen, to create and maintain off-screen graphics environments or whether you use GWorlds for the same purpose.
I Want the Best Performance!
As mentioned in the last paragraph, there’s nothing magical about GWorlds in most aspects. In one major aspect, there certainly is: the version of Color QuickDraw that runs with the 8•24 GC video card’s acceleration on knows about GWorlds and can cache their CGrafPort, PixMap, GDevice, inverse table, color table, and pixel image on the 8•24 GC card if there’s enough memory on it. When this is done, QuickDraw operations on the GWorld can be much faster than they’d normally be because the image data can stay in the card’s memory where the fast microprocessor is, and image data doesn’t have to move across NuBus in transfer operations between the GWorld and the screen. Additionally, these operations are executed asynchronously which increases the overall speed of your programs. For details about how the 8•24 GC card and GC QuickDraw work, see Guillermo Ortiz’s article, “Macintosh Display Card 8•24 GC: The Naked Truth,” in Issue 5 of develop.
8•24 GC QuickDraw doesn’t know about the off-screen graphics environments that you create, so it doesn’t cache its structures. All QuickDraw commands that move image data between the off-screen graphics environment and the screen have to move the data across NuBus, and that slows down the operation in comparison to keeping all the image data on the card.
If you want the highest possible drawing and copying performance with the 8•24 GC card, you must use GWorlds for your off-screen graphics environments.
I Want to Use a NuBus Memory Card for My GWorld’s Off-Screen Pixel Image
One common desire is to use a NuBus memory card to hold a pixel image. Because GWorlds are so easy to set up, and because GWorlds have all the same parts that you can make for an off-screen graphics environment, it’s tempting to make a GWorld and then point the baseAddr of the GWorld’s PixMap at the NuBus card’s memory. But GWorlds are designed to be fairly atomic structures, so they can’t be changed in this way. You can change a GWorld’s dimensions, depth, and color table because there’s a routine (_UpdateGWorld) that is designed to change these things, but you can’t change the pixel image without risking future compatibility.
If you want to have an off-screen graphics environment use a NuBus video card to store the pixel image, you should set up your own off-screen graphics environment rather than use GWorlds. This is covered earlier in this Note in “Choosing Your Off-Screen Memory.”
I Want My Program to Work on All System Software Releases
GWorlds have been around since 32-Bit QuickDraw was released (while system software version 6.0.3 was current). Until system software version 7.0, 32-Bit QuickDraw was an optional part of the system, so you aren’t guaranteed use of GWorlds even under recent system software releases. Obviously, if GWorlds aren’t available and your program still has to work with off-screen graphics environments, then there’s no choice but to use your own routines for creating, maintaining, and disposing of off-screen graphics environments. What’s usually done in these cases is to check via _Gestalt whether GWorlds are available or not. If they aren’t, then you create your off-screen graphics environment with your own routines. If they are, then you can use GWorlds without having to take up memory with your code for creating off-screen graphics environments yourself.
Are We There Yet?
Reliable, understandable, and maintainable off-screen drawing routines means not taking short-cuts. The most common problems that people run into with off-screen drawing routines is the appearance of strange colors and the gradual degradation of reliability as the program does more off-screen drawing. Building an off-screen graphics environment out of a CGrafPort, GDevice, and PixMap or by using GWorlds, combined with an understanding of how Color QuickDraw uses off-screen graphics environments, helps get rid of these problems. Hopefully, this Note helps you understand these things so that you can get better programs out the door faster.
Further Reference:
• Apple Computer, Inc., Inside Macintosh Volume I, Addison-Wesley, Reading, MA, 1985
• Apple Computer, Inc., Inside Macintosh Volume V, Addison-Wesley, Reading, MA, 1988.
• Apple Computer, Inc., Inside Macintosh Volume VI, Addison-Wesley, Reading, MA, 1991.
• Knaster, S., Macintosh Programming Secrets, Addison-Wesley, Reading, MA, 1988.
• Leak, B., “Realistic Color For Real-World Applications,” develop, January 1990, 4-21.
• Ortiz, G., “Braving Offscreen GWorlds,” develop, January 1990, 28-40.
• Ortiz, G., “Deaccelerated _CopyBits & 8•24 GC QuickDraw,” Macintosh Technical Note #289, January 1991.
• Ortiz, G., “Macintosh Display Card 8•24 GC: The Naked Truth,” develop, July 1990, 332-347.
• Othmer, K., “QuickDraw’s CopyBits Procedure: Better Than Ever in System 7.0,” develop, Spring 1991, 23-42.
• Tanaka, F., “Of Time and Space and _CopyBits,” Macintosh Technical Note #277, June 1990.
• Zap, J., F. Tanaka, J. Friedlander, and G. Jernigan, “Drawing Into an Off-Screen Bitmap,” Macintosh Technical Note #41, June 1990.
NuBus is a trademark of Texas Instruments.
Of Time and Space and _CopyBits
Imaging M.IM.TimeSpaceCopyBits
Written by: Forrest Tanaka June 1990
This Technical Note describes the various factors that can influence the speed of _CopyBits so that developers can set up conditions to achieve the best performance for the particular situation.
Can You Influence the Speed of _CopyBits?
_CopyBits has never been an “easy” QuickDraw routine, like _LineTo or even _OpenPort. Most programmers who are just beginning to adjust themselves to the Macintosh usually have to give _CopyBits a few tries before the right bits copy to the right places. Even many who feel that they have become Macintosh programmers still see reflections in their monitors of furrows between their eyebrows as they begin to press the key labelled “C.”
_CopyBits is one of those routines that is so full of subtlety, it has the beginnings of something that could be considered to be personality. One subtlety involves the second most important thought that’s on the minds of any computer programmer: execution speed. Why is _CopyBits fast? Why is it slow? Can I influence its speed? Is there really a clandestine state of reason? Is there a price to speed?
Influences on the Speed of _CopyBits
Yes, you can influence the speed of _CopyBits. Yes, it’s even predictable. And yes, it’s possible that you have to compromise to get the maximum speed. This Note is intended to give you a deeper understanding of the ways that the speed of _CopyBits can be affected; and hopefully you can then set up conditions for a _CopyBits call without the disturbing notion that someone else might be doing the same thing just a little bit better than you.
This Note talks about every factor that affects the speed of _CopyBits that I can think of and that can be reasonably controlled by a programmer or the person using an application. There are other factors not mentioned in this Note because I felt that they were just too esoteric to describe with any meaning.
In each case, this Note tries to give real-life examples showing the effect of each factor. These examples are just to give you a relative idea of the importance of each effect. In real life, the effects of the different factors give results that could be a lot different from the results presented in this Note. Each example is based on 100 _CopyBits calls from an off-screen pixel map to the screen on a Macintosh IIcx with an Apple Extended Video Card which is running System Software 6.0.5 and 32-Bit QuickDraw 1.2. The off-screen pixel map is eight bits deep with the standard eight-bit color table and 256 pixels high by 256 pixels wide. The screen is also in eight-bit color mode. Calling _CopyBits to copy the entire off-screen pixel map to the screen 100 times takes 204 ticks, and this Note refers to this figure as the “standard test.” Since a tick on a Macintosh is approximately 1/60 of a second, the standard test runs at slightly less than 30 frames per second. As this Note discusses each factor, it presents an example with that factor changing and all other factors remaining the same as the standard test, which allows you to compare performance of the changed factor to that of the standard test of 204 ticks.
What follows is a discussion of each factor that can influence the speed of _CopyBits, in no particular order.
Dimensions of the Copied Area
One of the most obvious factors has to do with the dimensions of the copied area. _CopyBits takes as parameters two rectangles which specify the portion of the source pixel map from which you want to copy and the portion of the destination pixel map to which you want to copy it. All other factors being equal, the larger the rectangles, the more pixels _CopyBits has to copy and the longer it takes to do the job. To keep _CopyBits as fast as possible, copy the smallest rectangle possible.
Modifying the standard test so that _CopyBits only copies a 128-pixel wide by 128-pixel tall area produces a result of 109 ticks, which compares to the 204 tick performance for a 256-pixel wide by 256-pixel tall area.
QuickDraw is usually faster drawing wide things than it is drawing tall things, because consecutive pixels in memory are displayed horizontally. Drawing a series of pixels that are next to each other horizontally is easy because QuickDraw simply has to set consecutive memory locations, while drawing a series of pixels that are next to each other vertically is just a little bit harder because the address of each pixel must be calculated. _CopyBits is no exception to this general rule; it copies a row of pixels, goes to the next row, copies that row, goes to the next row, and so on. The time spent going between rows is a lot more than the time going between pixels on one row, so the effect is that _CopyBits is faster copying a short and wide section of a pixel map than it is copying a tall and narrow one. To keep _CopyBits as fast as possible, copy the shortest rectangle possible.
Modifying the standard test again so that the source and destination rectangles are 256 pixels wide by 50 pixels tall produces a result of 110 ticks, while modifying it so that the source and destination rectangles are 50 pixels wide by 256 pixels tall results in a time of 123 ticks. These 13 ticks may not seem like a big deal, but combined with other factors, there may be a case where they make a big difference.
Shape and Size of the Clip, Visible, and Mask Regions
_CopyBits always makes sure that it stays within the lines, so to speak. _CopyBits copies pixels clipped to the maskRgn that you pass as the last parameter to the call. If the destination is the current GrafPort, _CopyBits additionally clips to a region that’s the intersection of the clipRgn and visRgn of the port. If the intersection of these three regions is not rectangular, then _CopyBits has to check each pixel to make sure it falls within the intersection, and this check slows _CopyBits down. If the intersection of these three regions is rectangular, then _CopyBits takes the fast case of copying constant-sized rows. To keep _CopyBits as fast as possible, make sure the intersection of the clipRgn and visRgn of the destination GrafPort and the maskRgn is rectangular. Of course, if the destination GrafPort is a window, then the visRgn is under the user’s control.
In general, if the region that you are copying into has straight vertical edges for the most part, the time penalty of using a non-rectangular region is not that bad. Regions that only have small portions that are straight and vertical are the ones that slow _CopyBits down in a big way. Regions that are twisted or that have holes or islands can also have a big effect upon the speed, depending upon how complicated they are. As a rule of thumb, if a region looks like it slows _CopyBits, it probably does.
Modifying the standard test so the maskRgn is set to a circle that inscribes the example pixel map results in a time of 303 ticks, which is considerably longer than the standard test result of 204 ticks that involved copying a much larger area. Modifying the maskRgn to a square with 226 pixels per side, which has about the same total area of the circle just used, results in a time of 176 ticks.
Transfer Modes
Macintoshes without Color QuickDraw have eight transfer modes that work with _CopyBits, while those Macintoshes with Color QuickDraw get an additional nine modes. Because the algorithms for each of these modes can be pretty different from the others, the time it takes _CopyBits to work with each of these modes can vary radically. For several of these modes, the speed of _CopyBits can vary a lot depending upon the particular image being copied and the image over which this image is copied. It can also vary non-linearly depending upon the depth of the pixel maps. The arithmetic modes in particular are highly optimized for 32-bit deep pixel maps.
The standard test copies a fairly average-looking ray-traced image to a white background. Modifying the standard test to erase the background between each of the 100 calls to _CopyBits produced the following results for the modes listed (the tests were obviously also changed to reflect the proper mode. In addition, to make the results a little more meaningful, the time it took to erase the background has been subtracted from each result.
Of course, the amount of time taken by some of these modes can be changed by changing the image to copy and the image over which it is copied. These figures are just to give an idea of how fast or slow some of these modes are in this particular situation.
There is actually one more mode which is not mentioned: ditherCopy. Apple introduced this mode with 32-Bit QuickDraw, and it makes _CopyBits do error-diffusion dithering when copying a pixel map from one depth to a pixel map of a lesser depth or to a pixel map of the same depth with a different color table. The speed of this transfer mode can be very fast or very slow, depending upon what pixel depths and colors are used and the particular image being copied. The ditherCopy mode is not included in the table since the range of figures is potentially very large; play with it and see for yourself. For more information about this mode, refer to the Color QuickDraw chapter in Inside Macintosh, Volume VI and the 32-Bit QuickDraw Developers’ Notes from APDA.
Colorization
There is a variation of _CopyBits if the destination pixel map is the current port and the foreground color is not black or the background color is not white. If this is the case, then the source image is colorized when it’s copied. For details, see Technical Note #163, Adding Color with _CopyBits. Because this colorization requires extra processing, _CopyBits slows down. To keep _CopyBits as fast as possible, make sure the foreground color is black, the background color is white, and that the current GDevice pixel map’s color table has white in the first position and black in the last position.
Modifying the standard test so that the foreground color is pure red and the background color pure blue produces a result of 579 ticks.
Pixel Alignment
The alignment of pixels in the source pixel map relative to their alignment the destination pixel map can be surprisingly important to the speed of _CopyBits, but what is pixel alignment? Following is an example to demonstrate the concept of pixel alignment. Imagine you want to perform a _CopyBits on a one-bit-per-pixel off-screen pixel map into a window on a one-bit-per-pixel screen, and the window is three pixels from the left edge of the screen.
If you copy the entire off-screen pixel map to the left edge of the window, then _CopyBits must realign the pixels. Since the leftmost pixels of the off-screen pixel map are on a byte boundary, but the left edge of the window is three pixels away from a byte boundary, _CopyBits has to shift (or realign) each byte from the off-screen pixel map by three pixels before placing it on the screen. The process of aligning the pixels slows down _CopyBits.
Figure 1 shows an example of this realignment. An off-screen bit map specified by a pointer to a BitMap called offScreen is being copied to a window specified by a WindowPtr called window. window, which is 256 pixels wide and 256 pixels high, is positioned 50 pixels from the top of the screen and three pixels from the left edge of the screen. The screen has 512 pixels horizontally and 342 pixels vertically. The source rectangle that is passed to _CopyBits is sourceRect and the destination rectangle is destinationRect. Because offScreen is misaligned by three pixels, _CopyBits has to shift offScreen by three pixels before placing the image on the screen.
Figure 1–offscreen Needs Realignment
By adjusting the off-screen pixel map so that its leftmost pixels are also three pixels away from a byte boundary, _CopyBits can just copy the bytes without shifting, which is a lot faster. This example holds true on all Macintosh models, whether they have Color QuickDraw or not. To keep _CopyBits as fast as possible, make sure the pixels in memory are aligned with the pixels on the screen. Figure 2 shows the same situation as Figure 1, except that offScreen is now properly aligned to window.
Figure 2–offscreen Aligned
Many, if not most, Color QuickDraw Macintoshes have video cards that can display one pixel per byte, so one would think that pixel alignment does not apply in these cases, since all pixels are at byte boundaries. This statement is true enough, but there is still another kind of alignment that should be done on these machines. Macintoshes with Color QuickDraw generally have full 32-bit microprocessors, and these microprocessors are at their fastest when they can transfer long words aligned on long-word boundaries in memory.
Modifying the last example so that the off-screen pixel map and the screen are both eight-bits-per-pixel, the pixel at the extreme top left corner of the off-screen pixel map is located at a long-word boundary, because the Macintosh Memory Manager forces it to be located there; however, the pixel at the extreme top left corner of the window is located three bytes away from the previous long-word boundary. No bit shifting is needed, because each pixel takes up a whole byte, but _CopyBits does have to take the non-optimum case of copying long words on non-long-word boundaries. This case works fine, but it is not quite as fast as it could be. To keep _CopyBits as fast as possible, make sure pixels in the source and destination pixel maps are aligned on long-word boundaries.
Since 1984, Macintosh programmers have been told that rowBytes must be even. That is still true, but to allow _CopyBits to copy an entire pixel map on long-word boundaries, rowBytes must be a multiple of four so that every line in a pixel map begins on a long-word boundary. The following formula can be used to find the minimum rowBytes needed for a pixel map’s bounds rectangle with right and left coordinates of bounds.right and bounds.left, and a pixel depth of pixelDepth:
Off-screen GWorld support, which was introduced with 32-Bit QuickDraw, can automatically set up a pixel map so that it’s properly aligned to any part of the destination pixel map or bit map. You can specify that you want this by passing zero for the pixel depth and passing the rectangle of the destination area in global coordinates. See the 32-Bit QuickDraw Developers’ Notes and “Braving Offscreen Worlds” in d e v e l o p, January 1990 for details.
The way that _NewGWorld aligns a GWorld is to set up the off-screen pixel map so that its rowBytes is four bytes wider than one would normally calculate. Four bytes is the maximum amount that any pixel map would have to be realigned at any pixel depth. The bounds rectangle’s left coordinate is set to the negative of the left coordinate of the destination rectangle in global coordinates modulo (32 / pixel depth), because this is maximum amount that a pixel map must be shifted to achieve perfect alignment. To build on the earlier example, assume you have a 128-pixel wide, eight-bit deep, off-screen pixel map to copy to a window that is three pixels away from the left edge of an eight-bit color screen.
First, the rowBytes for the off-screen pixel map is set to 131 to allow room for realignment. To align the off-screen pixel map to the on-screen window, the left coordinate of the off-screen bit map’s bounds is set to -3 and the right coordinate is still at 128. Notice that the off-screen pixel map’s bounds is now 131 pixels wide. Now, the pixels in the off-screen pixel map with a horizontal coordinate of 0 are located three bytes away from the previous long-word boundary. The pixels on the left edge of the window are also located three bytes away from the previous long-word boundary, so _CopyBits can copy long words on long-word boundaries.
If a user moves the window so that it’s two pixels from the left edge of the screen, the off-screen pixel map must be realigned. _UpdateGWorld is used to do this. It changes the left coordinate of the off-screen pixel map’s bounds rectangle to -2 and then it shifts all the pixels in the off-screen pixel map one pixel to the left. The extra four bytes in each row provide the room for this shifting. (Gives you some new respect for the off-screen support, doesn’t it?)
This same discussion applies to any pixel depth, though shallower pixel depths require bit shifting rather than byte shifting. The same principles apply, though. Notice that in a 32-bit deep pixel map, all pixels are aligned on long-word boundaries, so no bit shifting or byte shifting ever needs to be done on one of those. _NewGWorld still adds four to rowBytes even in this case, however.
Modifying the standard test so that the source and destination pixel maps are four bits deep with perfect pixel alignment produces a result of 78 ticks; however, if the destination pixel map is one pixel left of perfect alignment, the result is 228 ticks.
Speed of the Hardware, Of Course
Obviously, the speed of the machine your application is running on affects the speed of _CopyBits. To make _CopyBits as fast as possible, spend a lot of money. However, there is more to the speed of _CopyBits than the speed of the Macintosh itself. When the Macintosh 128K was released, there was only one place for pixel images: main memory. Today, the situation is more complicated. If you have a modular Macintosh, the pixel image for the screen is in the memory of a NuBus™ video card. If you have a Macintosh IIci, you can optionally abandon the NuBus video card and use on-board video which takes up part of main memory. If you have an 8•24 GC card with enough memory, the pixel images can be cached in the card’s memory along with the screen’s pixel image.
All of these different locations have different access speeds, and that can affect the speed of _CopyBits. Additionally, different Macintoshes have different RAM access speeds. The Macintosh II, IIx, IIcx, and SE/30 have faster RAM than the Macintosh Plus or SE. The Macintosh IIci RAM access speed is faster still, and the Macintosh IIfx has faster RAM access than the IIci. Different video cards have different access speeds. The IIci has a cache card option which can vastly speed up on-board video RAM access speed. Third-party video cards that work in the Processor Direct Slot of the Macintosh SE and SE/30 have their own speed characteristics as well.
There can also be a speed cost for crossing the different areas. If _CopyBits copies between main memory and a NuBus video card, the image data has to be transferred across NuBus. NuBus is a speed bottleneck, so copying an image across NuBus is slower than copying the image from one part of the screen to another or copying from one part of main memory to another. Modifying the standard test to create two windows and two off-screen pixel maps—all eight bits deep with the standard color table then doing every combination of copying between off-screens, between windows, and between off-screens and windows produces the following results:
Off-screen to off-screen: 147
Screen to screen: 188
Off-screen to screen: 204
Screen to off-screen: 201
Performing the standard test on a Macintosh IIfx running System Software 6.0.5 with an Apple Extended Video Card yields a result of 153 ticks, which is not too shabby considering that the transfer is still going through NuBus.
Depth of Pixel Maps
This factor is pretty obvious and is sort of similar to the effect of the dimensions of the copied area: the more bits per pixel there are in the pixel map to copy, the more memory that _CopyBits has to move and the longer it takes to get the job done, assuming that the source and destination pixel maps have the same depth. To make _CopyBits as fast as possible, make sure the pixel maps are as shallow as possible.
If _CopyBits has to copy to a pixel map that has a different depth from the source pixel map, the relationship between speed and depth becomes more complicated. There is a tradeoff between the time taken to change the depth of an image and the absolute amount of data that has to be processed. Copying from a 1-bit deep pixel map to a 32-bit deep pixel map is not that slow because the amount of image data in the 1-bit deep pixel map is so small.
Modifying the standard test to transfer a four-bit deep pixel map to another four-bit deep pixel map produces a result of 78 ticks.
Color Mapping
Color QuickDraw expects a color table attached to every indexed pixel map. Color tables specify what color each pixel value in the pixel map represents. When an application calls _CopyBits to copy a pixel map into another pixel map, _CopyBits reproduces the colors of the image in the source pixel map as closely as possible—even if the colors available in the destination pixel map are different than those available in the source pixel map. This reproduction is done through a process called “color mapping.”
When color mapping is done, the source pixel values are transformed into RGBColor records using the source pixel map’s color table. These RGBColor records are passed to _Color2Index which finds the pixel values of the closest available colors in the current GDevice pixel map’s color table. This same process is done when the source and destination pixel maps have differing depths. The color table attached to the destination pixel map is not used in color mapping. The colors available in the current GDevice pixel map’s color table are used instead. So, the destination pixel map must have the same colors for the same pixel values as the current GDevice. Otherwise, the resulting image in the destination pixel map gets the wrong colors. See Inside Macintosh, Volume V-141, The Color Manager, for a description of _Color2Index. It’s also helpful to read the “Inverse Tables” section in the same chapter on page V-137.
Now, if the source color table contains virtually the same colors for the same pixel values as the current GDevice pixel map’s color table, then any particular pixel value has the same color regardless of whether it is in the source or destination pixel map. In this case, color mapping is a waste of time, because the pixels can be copied directly from the source pixel map to the destination pixel map without a loss of color fidelity. _CopyBits takes advantage of this special case to yield some big speed improvements. How is this special case detected? Before this question is answered, it’s useful to understand how Color QuickDraw uses color tables.
The ctSeed Field
The first field in a color table is the ctSeed field. This LongInt can be thought of as the color table’s version of the scrapCount field of the desk scrap. Whenever an application calls _ZeroScrap, the desk scrap’s scrapCount is changed. An application can tell that the desk scrap has changed by checking to see if the scrapCount has changed. Similarly, whenever the contents of a color table are changed in any way, the ctSeed field should be changed to indicate to anyone using that color table that it has been modified.
Additionally, Color QuickDraw often uses the ctSeed as a fast check for color table equality. If two color tables have the same ctSeed, then Color QuickDraw often assumes that their contents are equivalent.
After creating a new color table, an application has to get a valid value for the ctSeed field, and it can do so with the _GetCTSeed routine. This routine generates a valid ctSeed value suitable for a new color table. See Inside Macintosh, Volume V-143, The Color Manager, for a description of _GetCTSeed.
System Software 7.0 and 32-Bit QuickDraw each offer a routine called _CTabChanged which should be called after a color table is modified. It takes a handle to the changed color table as a parameter. If the _CTabChanged routine is not available, then the application should instead change ctSeed to a different valid value by calling _GetCTSeed and assigning the result to ctSeed, just like it’s done when the application creates a new color table. You must use either one of these methods to tell Color QuickDraw that the color table has changed, or else the modified color table could be confused with the old color table, or with some other color table—this is especially critical if an 8•24 GC card is being used. See the 32-Bit QuickDraw Developers’ Notes for details about the _CTabChanged routine.
The ctFlags Field
The ctFlags field is used as a set of flags that indicate some characteristics of the color table. Currently, only the top two bits of ctFlags are of any interest to developers. The most significant bit of ctFlags (bit 15) indicates whether the color table is a sequential color table or an indexed color table. Bit 14 indicates that the color table is a special kind of sequential table if it is set. In these kinds of color tables, the value fields indicate a palette entry in the destination window’s palette. See the Palette Manager section of the 32-Bit QuickDraw Developers’ Notes for a discussion about this capability.
Sequential Color Tables
If bit 15 of ctFlags is set, the color table is a sequential color table. Sequential color tables are usually found attached to GDevice pixel maps and to GWorld pixel maps.
In sequential color tables, the position of each color in the color table indicates the pixel value to which it corresponds. For example, the fifth entry in a sequential color table always has a pixel value of four (pixel values start at zero). The value field of each ColorSpec is not defined in sequential color tables, though they are used in color tables for screen GDevice records to indicate that a particular color is reserved, protected, or both.
Indexed Color Tables
If bit 15 and 14 of ctFlags are clear, the color table is an indexed color table. In indexed color tables, the value field of each ColorSpec indicates the pixel value of the RGB in that ColorSpec. For example, if the fifth ColorSpec in the color table has a value field containing 10, then that color has a pixel value of 10, not 4, as it would have been if this were a sequential color table.
Color Mapping or Non-Color Mapping
As noted before, _CopyBits can detect whether it has to do color mapping or not, so that it can take advantage of the speed benefits of no color mapping if possible. How is this done? First, _CopyBits checks to see if the ctSeed field of the source and destination color tables are the same and if the source and destination pixel maps have the same depths. If both of these conditions are true, then _CopyBits assumes that the two color tables are identical and it just copies the pixels directly without color mapping. If the ctSeed fields are different, _CopyBits checks manually through all of the colors in the source pixel map’s color table map to see if they map to the same pixel values in the current GDevice pixel map’s color table as they do in their own color table. If they do, then _CopyBits again takes the fast case.
So to keep _CopyBits as fast as possible, make sure that the source and destination color tables have virtually the same colors for the same pixel values. This applies even if one color table is an indexed color table and the other is a sequential color table, or if the source and destination color tables are both indexed but the order of the ColorSpec records differ.
Modifying the standard test so that the source pixel map has a color table that is the reverse of the standard eight-bit system color table (the grays have low pixel values and the light pinks and yellows have high pixel values) and the destination pixel map has the standard eight-bit system color table produces a result of 470 ticks.
By the way, color tables do not make any sense for direct pixel maps, so this discussion does not apply to them. Direct pixel maps do have a color table attached to them, but they’re just there so that an application that assumes that a color table is attached does not bomb.
Scaling
If the source and destination rectangles are the same size, _CopyBits has the fairly easy task of just transferring the pixels from the source pixel map to the destination pixel map; however, if the source and destination rectangles are different sizes, _CopyBits has to scale the copied image, which slows it down a lot. To keep _CopyBits as fast as possible, make sure the source and destination rectangles have the exact same dimensions.
Modifying the standard test to copy a 128 by 128 pixel portion of the source pixel map to the whole 256 by 256 pixel window produces a result of 1,159 ticks.
Of Time and Space
Hopefully, this Note makes it a lot clearer to you how to set up a situation in which your _CopyBits calls are as fast as your situation allows. It’s important to realize that this Note does not cover every single factor that has an influence on the speed of _CopyBits. There are many more factors which are just too unpredictable. For example, _CopyBits is highly optimized for many special cases, and those optimizations can have a big effect on the speed of the copy. Also, the speed of _CopyBits can be affected by interrupt-level tasks. It’s up to you to fine tune your programs to your particular situations.
Further Reference:
• Inside Macintosh, Volume I, QuickDraw
• Inside Macintosh, Volume V, The Color Manager
• Inside Macintosh, Volume VI, Color QuickDraw
• Technical Note M.IM.ColorCopyBits, Adding Color With _CopyBits
• d e v e l o p, January 1990, “Realistic Color for Real-World Applications”
• d e v e l o p, January 1990, “Braving Offscreen GWorlds”
• 32-Bit QuickDraw Developers’ Notes (APDA)
NuBus is a trademark of Texas Instruments
‚ ◊# ˇ ˇˇˇˇ # ◊ ° d WORD S † å ° d WORD R… † Ç
/ Z Å#
0Ià:µú9 " { ˇˇˇˇˇˇˇˇ # † ƒ ° d
ONLN f ˛ † å ° d 1drw2 … -·_ Ä ˇˇˇˇˇˇ è ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˙ ó@ † ò , Times
. WIQkWIQk +]BNew Technical Notes † ô ° d drw2 : °„ † ó ° d 1drw2 eÙ Ä ˇˇˇˇˇˇ P ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä E¿ † ò
Ä ( {ïDeveloper Support † ô ° d drw2 : °„ † ó ° d `drw2 - Ô ˇˇˇˇˇˇ K Ô - Z f f Z ° d 1drw2 ¿˙È ˇˇˇˇˇˇ K ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : 0 ° ö ˇÙ Ä † ò
0 ( UÔ † ô ° d drw2 : °„ † ó ° d 1drw2 ÔÊ˙ ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˝Ä † ò
l +& ® † ô ° d drw2 : °„ † ó ° d 1drw2  -¯ y ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä % † ò
BÄ ( Z \ Macintosh † ô ° d drw2 : °„ † ó † ç ° d drw2 D † É ° d WORD † ç
IR . ° d ONLN d { < éë ( ® Z'32-Bit QuickDraw: Version 1.2 Features
° d ONLN d ( ç < ú r *Imaging ° d ONLN d 0 çö ú˛ ( ∏∏ M.IM.32BitQD
° d ONLN d = ® < ¥ q ( – Z Written by: ° d ONLN d I ® Ñ ¥ Œ )HGuillermo Ortiz ° d ONLN d Y ®À ¥˛ ( –È
April 1990 ° d ONLN d d ¿ < ÃÁ ( Ë ZOThis Technical Note describes the changes and enhancements to 32-Bit QuickDraw ° d ONLN d ≥ ¿Á Ã˛ ( Ëfrom ° d ONLN d ∏ à < ÿ b ( Ù Zversion ° d ONLN d ¿ à b ÿ˛ )&S1.0 (as shipped on the original Color Disk) to version 1.2, which ships with System ° d ONLN d ÿ < ‰R ( Z9Software 6.0.5 and later. This Note assumes familiarity ° d ONLN dM ÿR ‰l ( pwith ° d ONLN dR ÿl ‰ø )Inside Macintosh ° d ONLN db ÿø ‰˛ )S , Volume V, ° d ONLN dn ‰ < E ( Z4Color QuickDraw, and 32-Bit QuickDraw release notes. X
° d ONLN d£ <$ ∂ *432-Bit QuickDraw
° d ONLN d¥0 <<® *GVersion 1.0 of 32-Bit QuickDraw shipped in May 1989 in response to the ° d ONLN d˚0®<˛ (XΔgrowing need for ° d ONLN d < <H Z (d ZColor ° d ONLN d< ZH˛ ) TQuickDraw support for direct color devices and pictures (PICT2) and video boards for ° d ONLN dgH <T y (p Z
large-screen ° d ONLN dtH yT˛ )=Mmonitors which require 32-bit addressing for black and white operation. This ° d ONLN d¬T <` (| Z]original version of 32-Bit QuickDraw was a separate file that had to be copied manually into ° d ONLN d T`˛ (|the ° d ONLN d#` <l (à Z-System Folder. With the introduction of the ° d ONLN dP`l˛ )‘/Macintosh IIci, Apple put 32-Bit QuickDraw into ° d ONLN dÄl <xà (î ZPROM. Now System Software 6.0.5 and later offer 32-Bit QuickDraw as an integral ° d ONLN d–lÃx˛ (îÍ part of the ° d ONLN d‹x <ÑÉ († ZASystem Software which can be installed by the standard Installer ° d ONLN d xÉÑ˛ (†°(although the file is still ° d ONLN d9Ñ <ê j (¨ Z
separate). ° d ONLN dDú <® n *
This Note ° d ONLN dNú n®˛ )2Ndescribes the changes and enhancements in version 1.2 of 32-Bit QuickDraw from ° d ONLN dù® <¥ Õ (– Z version 1.0. Beginning with ° d ONLN d∫® Õ¥˛ )ë>version 1.2, QuickDraw functionality is identical on all Color ° d ONLN d˘¥ <¿ ˆ (‹ Z&QuickDraw machines, including all the ° d ONLN d ¥ ˆ¿˛ )∫3performance improvements which were originally only ° d ONLN dS¿ <à ∂ (Ë Zavailable in the IIci ROM.
° d ONLN dn‰ <ÛB *'%New Features (In No Particular Order)
° d ONLN dîˇ < *#PICTs Contain Font Name Information ° d ONLN d∏ <$ *&Every time you draw text inside of an ,
Courier ° d ONLN dfi#d )‘ _OpenPicture ° d ONLN dÍd$Ö )T and ° d ONLN dÔÖ#‡ )!
_ClosePicture ° d ONLN d¸‡$˛ )[ pair, ° d ONLN d$ <0E (L Z7QuickDraw stores the name of the current font and uses ° d ONLN d:$E0˛ (Lc&it when playing back the picture. The ° d ONLN da0 <<ë (X ZIopcode used to save this information is $002C and its data is as follows:
° d ONLN d´H <S π * PictFontInfo = Record ° d ONLN d≈R <]ü *
G length : Integer; { length of data in bytes } ° d ONLN d
\ <gü *
G fontID : Integer; { ID in the source system } ° d ONLN dUf <q ˇ *
' fontName : Str255; ° d ONLN d}p <{ Ø *
END;
° d ONLN dïÜ <í Δ *QuickDraw only saves this ° d ONLN dØÜ Δí˛ )ä;information one time for each font used in a picture. When ° d ONLN dÎì <ü ‚ (ª Z#QuickDraw plays back a picture, it ° d ONLN dì ‚ü
)¶ uses the ° d ONLN dí
û7 )+fontID ° d ONLN d ì7ü˛ )*+ as a reference into the list of font names ° d ONLN dIü <´N (« Z<which are used to set the correct font on the target system. ◊ X◊
*%'32-Bit QuickDraw: Version 1.2 Features (Ï1 ) of 5 ˇ ° ¿Ù%%DSIDICT:_cv
currentdict /bu known {bu}if
userdict /_cv known not{userdict /_cv 30 dict put}if
_cv begin
/bdf{bind def}bind def
currentscreen/cs exch def/ca exch def/cf exch def
/setcmykcolor where{/setcmykcolor get /cvcmyk exch def}{/cvcmyk{1 sub 4 1 roll 3{3 index add neg dup 0 lt{pop 0}if 3 1 roll}repeat setrgbcolor pop}bdf }ifelse
/ss{//cf //ca //cs setscreen}bdf
/stg{ss setgray}bdf
/strgb{ss setrgbcolor}bdf
/stcmyk{ss cvcmyk}bdf
/min1{dup 0 eq{pop 1}if}bdf
end
currentdict /bn known {bn}if
† ø¬ ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘
° d ONLN d ) 5 µ *$ For example, the following code: ,
Courier
° d ONLN d ! A Lv *F GetFNum('Venice', theFontID); { Set a font before opening PICT} ° d ONLN d h K V ê *
TextFont(theFontID); ° d ONLN d Å _ j — *% pHand2 := OpenPicture (pictRect); ° d ONLN d ß i t Ü *
MoveTo(20,20); ° d ONLN d æ s ~ ‡ *
( DrawString(' Better be Venice'); ° d ONLN d Á á í — *% GetFNum('Geneva', theFontID); ° d ONLN d
H TxFont 'geneva' /* second Geneva does not ° d ONLN d…√ Œä *
J need another $002C guy */ ° d ONLN dÕ ÿ ï *
DVText {20, "Geneva"}
° d ONLN d.„ Ô• *VThis feature works regardless of the type of picture being saved, including old style ° d ONLN dÑ„•Ô⁄ ( √
PICTs in a ° d ONLN dè ¸ ¥ ( 6 black and white port. Using ° d ONLN d¨Ô ¥˚ )ú
_OpenCPicture ° d ONLN dπ¸O )[ instead of ° d ONLN d≈ÔO˚£ )@ _OpenPicture ° d ONLN d—£¸⁄ )T to start a ° d ONLN d›¸ ($ 64recording session results in the same functionality. ° d ONLN d ˛ *&Direct PixPat Structures Now Supported ° d ONLN d9- 9 *3QuickDraw now supports 16-bit and 32-bit per pixel ° d ONLN dl,8= )˚PixPat ° d ONLN dr-=9u )*
structures ( ° d ONLN d,u8¬ )8 patType = 1 ° d ONLN dä-¬9– )M). ° d ONLN dé-–9⁄ )In ° d ONLN dë: F ± (b 6 addition, it now supports a new ° d ONLN d±9 ±E ‚ )ôpatType ° d ONLN d∏: ‚F ˆ )1 (3) ° d ONLN dΩ: ˆF⁄ ).which uses dithering whenever 16-bit or 32-bit ° d ONLN dÌF R ˘ (n 60pixel patterns are displayed on indexed devices. ° d ONLN d ^ j ˙ *%Direct 'cicn' Resources Now Supported ° d ONLN dDw É *3QuickDraw now supports 16-bit and 32-bit per pixel ° d ONLN dwvÇ= )˚'cicn' ° d ONLN d}w=É⁄ )*! resources. The 16-bit per pixel ° d ONLN düÑ êJ (¨ 6Dis particularly cool since you save the space required for an 8-bit ° d ONLN d„ÉJèt (¨h'clut' ° d ONLN dÈÑtêx )*. ◊ 4◊˘
(Ï 62 ) of 5 (ÏS'32-Bit QuickDraw: Version 1.2 Features ˇ( ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +Z-Developer Support Center ( -
April 1990 / X /
° d ONLN d ) < 5Ω ( Q Z<GWorlds Can Now Be Allocated in MultiFinder Temporary Memory ° d ONLN d = B < N S *You ° d ONLN d A B S N æ )can now use the new ,
Courier ° d ONLN d U A æ M )k
useMFTempBit ° d ONLN d b B Ns )\(bit 2) in a call to ° d ONLN d w As M≤ )Y NewGWorld ° d ONLN d Ä B≤ N˛ )? as an option to ° d ONLN d ë N < Z/ ( v Z1allocate pixels in MultiFinder temporary memory. ° d ONLN d ¬ N/ Z˛ )Û) In addition, you can now allocate screen ° d ONLN d Ï Z < f˛ ( Ç Z]buffers in MultiFinder temporary memory using the following routine, defined in Pascal and C:
° d ONLN dJ r < }ã *CFUNCTION NewTempScreenBuffer (globalRect: Rect; purgeable: BOOLEAN; ° d ONLN dé | < á, *
I VAR offscreenPixMap: PixMapHandle): QDErr; ° d ONLN d ê < õê *
D INLINE $203C,$000E, $0015,$AB1D; { Move.L #$000E0015,D0 ° d ONLN dN ö < •c *
; _QDOffscreen ° d ONLN dä § < Ø" *
. } ° d ONLN dπ ∏ < √ö *Fpascal QDErr NewTempScreenBuffer (Rect *globalRect, BOOLEAN purgeable, ° d ONLN d ¬ < Õ *
, GDHandle *gdh, ° d ONLN d- Ã < ◊h *
< PixMapHandle *offscreenPixMap) ° d ONLN dj ÷ < · *
, ={0x203C,0x000E,0x0015,0xAB1D};
° d ONLN dò Ï < ¯ ‚ * Indexed to Indexed Dithering ° d ONLN dµ < { * _CopyBits ° d ONLN dæ { ñ )? now ° d ONLN d√ ñ ’ )
supports the ° d ONLN d– ’ )?
ditherCopy ° d ONLN d⁄˛ )F. transfer mode whenever the destination device ° d ONLN d < 7 (9 Z7is between one and eight bits per pixel, regardless of ° d ONLN d@7 ˛ )˚)the depth of the source image. With this ° d ONLN dj <)ä (E ZFsupport, an eight-bit image can now be approximated on a one-bit or a ° d ONLN d∞ ä)˛ (E®four-bit device by using ° d ONLN d…) <5Õ (Q ZXerror diffusion. Furthermore, an eight-bit image could also be dithered to a different ° d ONLN d!)Õ5˛ (QÎ
set of 256 ° d ONLN d,5 <Aù (] ZNcolors or a four-bit image could be dithered to an eight-bit device that does ° d ONLN dz5ùA˛ (]ªnot have the desired ° d ONLN dèA <M ] (i Zcolors. ° d ONLN dóY <e *"32-Bit Addressed PixMap Structures ° d ONLN d∫r <~ § *Version 1.2 defines a ° d ONLN d–r §~ º )hnew ° d ONLN d‘q º} ˚ ) pmVersion ° d ONLN d›r ˚~ )? ( ° d ONLN dflq}g )baseAddr32 = 4 ° d ONLN dÌrg~Δ )d) for 32-bit pointer ° d ONLN dqΔ}˛ )_baseAddr ° d ONLN d <ã (ß Z
values. The ° d ONLN d~ ä ∑ )CbaseAddr ° d ONLN d ∑ã Ê )8 of such ° d ONLN d)~ Êä )/PixMap ° d ONLN d/ã≥ )*# structures is treated as a 32-bit ° d ONLN dR≥ã˛ )£address, so no ° d ONLN daã <óú (≥ ZJstripping or address translation is performed on it in 32-bit mode. This ° d ONLN d´ãúó˛ (≥∫is a specially useful ° d ONLN d¡ò <§ Ë (¿ Z#feature when the base address of a ° d ONLN d‰ó Ë£ )¨PixMap ° d ONLN dÍò§ )* ° d ONLN dÎò§r )points to a NuBus
° d ONLN d¸ñr°z (Ωê™
° d ONLN d˝òz§˛ + address, for example in a ° d ONLN d§ <∞ ü (à Zvideo grabber board. ° d ONLN d-Ω <… x * A new call, ° d ONLN d9º x» ≈ )< Pixmap32Bit ° d ONLN dDΩ ≈… )M, is now available ° d ONLN dWΩ …à )Zto inquire if a given ° d ONLN dmºà»≤ )iPixMap ° d ONLN dsΩ≤…˛ )* requires 32-bit ° d ONLN dÑ… <’ s (Ò Z addressing.
° d ONLN dê· <Ï' */FUNCTION Pixmap32Bit(pmh:pixMapHandle):Boolean; ° d ONLN d¿Î <ˆc *
_OpenCPicture ° d ONLN dÛ ö ¶⁄ )[-, to create pictures that contain information ° d ONLN d! ¶ ≤ Ù ( Œ 60regarding the native resolution of the recorded ° d ONLN dQ ¶ Ù ≤⁄ )‹-image. When QuickDraw draws this picture, it ° d ONLN d ≤ æ† ( ⁄ 6Qscales the image to the resolution of the target device. Applications that need ° d ONLN d– ≤† æ⁄ ( ⁄æ to scale the ° d ONLN d› æ ˚ ( Ê 61images directly can also access this information.
° d ONLN d ÷ ·? *;FUNCTION OpenCPicture(VAR CPictInfo:CPictRecord):PicHandle; ° d ONLN dK ‡ Î m *
INLINE $AA20; ° d ONLN d] Ù ˇ! *5pascal PicHandle OpenCPicture(CPictRecord *CPictInfo) ° d ONLN dì ˛ ^ *
= 0xAA20;
° d ONLN d¢ 5 *where
° d ONLN d®, 7 | *struct CPictRecord { ° d ONLN dΩ6 A∑ *
S Rect CPicFrame; /* Bounding rect of Picture at native resolution */ ° d ONLN d@ K∑ *
S Fixed CPicHRes; /* native horizontal resolution in pixels/inch */ ° d ONLN deJ U∑ *
S Fixed CPicVRes; /* native vertical resolution in pixels/inch */ ° d ONLN dπT _∑ *
S short CPicVersion; /* version of this PICT info set to -2 */ ° d ONLN d
^ i∑ *
S short reserved; /* for future expansion set to zero */ ° d ONLN dah s∑ *
S long reserved; /* for future expansion set to zero */ ° d ONLN dµr } J *
Size in bytes ° d ONLN d† √¨ „ )cName ° d ONLN d †/¨p )l Description À |Àµ ° d ONLN dÆ ∫ Ö (÷ ù2 ° d ONLN d≠ √π Ù )DpicSize ° d ONLN d Æ ∫ê )Zlow word of picture size ° d ONLN d:ª « Ö („ ù8 ° d ONLN d<∫ √Δ ˚ )DpicFrame ° d ONLN dEª «ã )Zbounding box at 72 dpi Ê |ʵ ° d ONLN d\‡ <Ï ê ( ZPicture Header X √ ° d ONLN dkÓ <˙ B *2 ° d ONLN dmÌ i˘ Ø )-
version op ° d ONLN dxÓ Ã˙? )cversion opcode = $0011 ° d ONLN dè˚ < B (# Z2 ° d ONLN dë˙ i ö )-version ° d ONLN dô˚ ÃC )cversion number = $02FF ° d ONLN d∞ < B (0 Z2 ° d ONLN d≤ i ® )- Header op ° d ONLN dº Ã@ )cheader opcode = $0C00 ° d ONLN d” <! B (= Z2 ° d ONLN d’ i ö )-version ° d ONLN d› Ã!H )c-2 for PICTs created with ° d ONLN d˜H £ )|
_OpenCPicture ° d ONLN d" <. B (J Z2 ° d ONLN d! i- ° )-reserved ° d ONLN d/ <; B (W Z4 ° d ONLN d. i: Ö )-HRes ° d ONLN d/ Ã;S )c native horizontal resolution ( ° d ONLN d5.S:v )áFixed ° d ONLN d:/v;z )#) ° d ONLN d<< <H B (d Z4 ° d ONLN d>; iG Ö )-VRes ° d ONLN dC< ÃHF )c native vertical resolution ( ° d ONLN d_;FGi )zFixed ° d ONLN dd<iHm )#) ° d ONLN dfI <U B (q Z8 ° d ONLN dhH iT ö )-SrcRect ° d ONLN dpI ÃU7 )cnative source rectangle ° d ONLN dàV <b B (~ Z4 ° d ONLN däU ia ° )-reserved Å XÅ√ ◊ 4◊˘
(Ï 64 ) of 5 (ÏS'32-Bit QuickDraw: Version 1.2 Features ˇF ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +Z-Developer Support Center ( -
April 1990 / X /
° d ONLN d * < 6 ( R Z,The following is a sample PICT created with ,
Courier ° d ONLN d , ) 5m )÷
_OpenCPicture ° d ONLN d 9 *m 6p )[:
° d ONLN d ; B < Mö ( i ZF 00 48 /* low word of size */ ° d ONLN d Ç L < Wö *
F 00 00 00 00 00 7D 00 7D /* picFrame at 72 dpi */ ° d ONLN d … V < aö *
F 00 11 /* PICT version opcode */ ° d ONLN d ` < kö *
F 02 FF /* version number */ ° d ONLN dW j < uö *
F 0C 00 /* PICT header Opcode */ ° d ONLN dû t < ö *
F FF FE /* PICT version -2 */ ° d ONLN d ~ < âö *
F 00 00 /* reserved */ ° d ONLN d, à < ìö *
F 01 20 00 00 /* HRes (Fixed) */ ° d ONLN ds í < ùö *
F 01 20 00 00 /* VRes (Fixed) */ ° d ONLN d∫ ú < ßö *
F 00 00 00 00 01 F4 01 F4 /* picFrame at native resolution */ ° d ONLN d ¶ < ±ö *
• ° d ONLN d<£ `Ø ± )Inside Macintosh ° d ONLN dL£ ±ØC )Q, Volume V, Color QuickDraw ° d ONLN dhØ Nª R (◊ l• ° d ONLN djØ `ªm )432-Bit QuickDraw Release Notes (available from APDA) ° d ONLN düª N« R („ l• ° d ONLN d°ª `« )$System Software 6.0.5 Change History ° d ONLN dΔ« N” R (Ô l• ° d ONLN d»« `” ó )
d e v e l o p ° d ONLN d’« ó” æ )7 , Issue I ° d ONLN dflfl <Î ( Z*NuBus is a trademark of Texas Instruments. ◊ X◊
*Â'32-Bit QuickDraw: Version 1.2 Features (Ï5 ) of 5 ˇ ◊# ˇ ˇˇˇˇ # ◊ † Ç
/ Z Å#
0Ià:µú9 " { ˇˇˇˇˇˇˇˇ # † ƒ ° d
ONLN f ˛ † å ° d 1drw2 … -·_ Ä ˇˇˇˇˇˇ è ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˙ ó@ † ò , Times
. R… R… +]BNew Technical Notes † ô ° d drw2 : °„ † ó ° d 1drw2 eÙ Ä ˇˇˇˇˇˇ P ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä E¿ † ò
( {ïDeveloper Support † ô ° d drw2 : °„ † ó ° d `drw2 - Ô ˇˇˇˇˇˇ K Ô - Z f f Z ° d 1drw2 ¿˙È ˇˇˇˇˇˇ K ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : 0 ° ö ˇÙ Ä † ò
0 ( UÔ † ô ° d drw2 : °„ † ó ° d 1drw2 ÔÊ˙ ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˝Ä † ò
+& ® † ô ° d drw2 : °„ † ó ° d 1drw2  -¯ y ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä % † ò
( Z \ Macintosh † ô ° d drw2 : °„ † ó † ç ° d drw2 D † É
IR . ° d ONLN d z < ç ( ß ZBasic QuickDraw Q&As
° d ONLN d å < õ r *Imaging ° d ONLN d ån õ˛ ( ∑åM.IM.BasicQD.Q&As
° d ONLN d / ß < ≥ t ( œ Z Revised by: ° d ONLN d ; ß Ñ ≥ ˇ )HDeveloper Support Center ° d ONLN d T ßæ ≥˛ ( œ‹ October 1992 ° d ONLN d a ≥ < ø q ( € Z Written by: ° d ONLN d m ≥ Ñ ø ˇ )HDeveloper Support Center ° d ONLN d Ü ≥æ ø˛ ( €‹ October 1990 ° d ONLN d ì À < ◊ ⁄ ( Û Z This Technical Note contains a ° d ONLN d ≤ À ⁄ ◊˛ )û9collection of Q&As relating to a specific topic—questions ° d ONLN d Ï ◊ < „† ( ˇ ZGyou’ve sent the Developer Support Center (DSC) along with answers from ° d ONLN d3 ◊† „˛ ( ˇæthe DSC engineers. ° d ONLN dF „ < Ô u ( Z
While DSC ° d ONLN dP „ u Ô˛ )9Lengineers have checked the Q&A content for accuracy, the Q&A Technical Notes ° d ONLN dù Ô < ˚ q ( Z don’t have ° d ONLN d® Ô q ˚˛ )5Qthe editing and organization of other Technical Notes. The Q&A function is to get ° d ONLN d˙ ˚ < Ÿ (# Z new technical information and ° d ONLN d ˚ Ÿ˛ )ù6updates to you quickly, saving the polish for when the ° d ONLN dO < (/ Z,information migrates into reference manuals. ° d ONLN d| <+k *:Q&As are now included with Technical Notes to make access ° d ONLN d∂ k+˛ (Gâ to technical updates easier for ° d ONLN d÷+ <7. (S Z/you. If you have comments or suggestions about ° d ONLN d+.7˛ )Ú*Q&A content or distribution, please let us ° d ONLN d07 <C \ (_ Zknow ° d ONLN d57 \C˛ ) Iby sending an AppleLink to DEVFEEDBACK. Apple Partners may send technical ° d ONLN dC <Oi (k Z9questions about Q&A content to DEVSUPPORT for resolution. ° d ONLN dπ[ <g« *NNew Q&As and Q&As revised this month are marked with a bar in the side margin. "z í Xí
° d ONLN då <õ† *42Sending PostScript via PostScriptHandle PicComment
° d ONLN d;õ <ß b * Written: ° d ONLN dDõ àß ¶ )L5/1/90 ° d ONLN dKß <≥ Å (œ ZLast reviewed: ° d ONLN dZß à≥ ¨ )L10/9/91 ° d ONLN dbø <À G (Á ZIf ° d ONLN deø GÀ˛ ) XI use the PostScriptHandle PicComment to send PostScript code to the LaserWriter driver, ° d ONLN dæÀ <◊£ (Û ZHdo I need to open a picture and then draw the picture to the driver, or ° d ONLN dÀ£◊˛ (Û¡can I just use the ° d ONLN d◊ <„õ (ˇ ZHPicComment with no picture open while drawing to the printer’s grafPort? ° d ONLN db„ <Ô N * ___ ° d ONLN df˚ < ò *You don’t need to ° d ONLN dx˚ ò˛ )\Gcreate a picture with your PicComment in it and draw the picture to the ° d ONLN d¿ < (/ ZQdriver. The best method for sending PostScript code to the LaserWriter is to use ° d ONLN d˛ (/the ° d ONLN d < _ (; Z8PostScriptHandle PicComment documented in the Macintosh ° d ONLN dM_ ˛ (;} Technical Note #91, “Optimizing ° d ONLN dm <+V (G Z6for the LaserWriter—Picture Comments,” as shown below. ,
Courier
° d ONLN d§7 <B á *PrOpenPage(...) ° d ONLN d¥A <Lc *
;{ Send some QuickDraw so that the Printing Manager gets a } ° d ONLN dK <V *
){ chance to define the clipping region. } ° d ONLN dU <` } *
PenSize(0,0); ° d ONLN d)_ <j x *
MoveTo(0,0); ° d ONLN d6i <t x *
LineTo(0,0); ° d ONLN dDs <~ } *
PenSize(1,1); ° d ONLN dS} <à *
$PicComment(PostScriptBegin, 0, NIL); ° d ONLN dxá <í *
({ QuickDraw representation of graphic. } ° d ONLN d°ë <ú ë *
MoveTo(100, 100); ° d ONLN d≥õ <¶ ë *
LineTo(200, 200); ◊ X◊
**Basic QuickDraw Q&As (Ïˇ1 ) of 22 ˇ ° ¿Ù%%DSIDICT:_cv
currentdict /bu known {bu}if
userdict /_cv known not{userdict /_cv 30 dict put}if
_cv begin
/bdf{bind def}bind def
currentscreen/cs exch def/ca exch def/cf exch def
/setcmykcolor where{/setcmykcolor get /cvcmyk exch def}{/cvcmyk{1 sub 4 1 roll 3{3 index add neg dup 0 lt{pop 0}if 3 1 roll}repeat setrgbcolor pop}bdf }ifelse
/ss{//cf //ca //cs setscreen}bdf
/stg{ss setgray}bdf
/strgb{ss setrgbcolor}bdf
/stcmyk{ss cvcmyk}bdf
/min1{dup 0 eq{pop 1}if}bdf
end
currentdict /bn known {bn}if
† ø* ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘ ,
Courier
° d ONLN d ( Â *){ PostScript representation of graphic. } ° d ONLN d * ' 20 *
8thePSHandle^^ := '100 100 moveto 200 200 lineto stroke'; ° d ONLN d c 1 <0 *
8PicComment(PostScriptHandle, GetHandleSize(thePSHandle), ° d ONLN d ú ; F ö *
thePSHandl); ° d ONLN d ∑ E P ¬ *
"PicComment(PostScriptEnd, 0, NIL); ° d ONLN d ⁄ O Z h *
PrClosePage(...)
° d ONLN d Î e qC *5The above code prints a line on any type of printer, ° d ONLN d eC q⁄ ( ça PostScript or not. The first ° d ONLN d= q } fi ( ô 6&MoveTo/LineTo combination is required ° d ONLN dc q fi }⁄ )Δ3to give the LaserWriter driver a chance to define a ° d ONLN dó } â A ( • 6 clipping ° d ONLN d† } A â⁄ ))Uregion. The LaserWriter driver replaces the grafProcs record in the grafPort returned ° d ONLN dˆ â ï} ( ± 6Kfrom PrOpenDoc. In order for the LaserWriter driver to get execution time, ° d ONLN dA â} ï⁄ ( ±õyou must execute a ° d ONLN dT ï °z ( Ω 6IQuickDraw drawing routine that calls one of the grafProcs. In this case, ° d ONLN dù ïz °⁄ ( Ωòthe MoveTo/LineTo ° d ONLN dØ ° ≠ç ( … 6Ocombination calls the StdLine grafProc. When StdLine executes, it notices that ° d ONLN d˛ °ç ≠⁄ ( …´the grafPort has ° d ONLN d ≠ πà ( ’ 6Vbeen reinitialized, and therefore initializes the clipping region for the port. Until ° d ONLN de ≠à π⁄ ( ’Íthe ° d ONLN di π ≈] ( · 6CMoveTo/LineTo combination is executed, the clipping region for the ° d ONLN d¨ π] ≈⁄ ( ·{ port is set to (0,0,0,0). If ° d ONLN d… ≈ —è ( Ì 6MPostScript code is sent via the PostScriptHandle PicComment before executing ° d ONLN d ≈è —⁄ ( Ì≠
any QuickDraw ° d ONLN d$ — ›? ( ˘ 6Aroutines, all PostScript operations will be clipped to (0,0,0,0). ° d ONLN df È ı ≠ * The next thing that’s done is ° d ONLN dÑ È ≠ ı⁄ )ï7to send the PostScriptBegin PicComment. This comment is ° d ONLN dº ı ( 64recognized only by PostScript printer drivers. When ° d ONLN d ı⁄ )˙*the driver receives this comment, it saves ° d ONLN d
v () 6the current state of ° d ONLN d0 v
⁄ )^Hthe PostScript device (by executing the PostScript gsave operator), then ° d ONLN dy
ÃT ª`⁄ )£=PostScript, which is a data structure defining the context in ° d ONLN d
` l5 (à 68which other graphic operators in PostScript execute. If ° d ONLN d B`5l⁄ (àS you don’t know PostScript, the ° d ONLN d al x ¶ (î 6 following manuals are a must: ° d ONLN d Ñ ê *• ° d ONLN d ÅÑ !ê é ) PostScript Language ° d ONLN d ïÑ éê⁄ )m<Tutorial and Cookbook (Addison-Wesley) is an introduction to ° d ONLN d “ê !úx (∏ ?DPostScript. • PostScript Language Reference Manual (Addison-Wesley). ◊ 4◊˘
(Ï 62 ) of 22 (ÏñBasic QuickDraw Q&As ˇ
◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +Z-Developer Support Center ( -Ê October 1992 / X /
° d ONLN d < ) @ ( E Z• ° d ONLN d E )ü ) <PostScript Language Program Design (Addison-Wesley) details ° d ONLN d > ü )˛ ( EΩdesigning efficient ° d ONLN d R ) E 5 ı ( Q c%PostScript programs. It has a lot of ° d ONLN d w ) ı 5˛ )∞5useful sample programs on topics like writing a print ° d ONLN d ≠ 5 E A l ( ] cspooler. ° d ONLN d ∂ M < Y: ( u Z1You need to convert all the QuickDraw operations ° d ONLN d Á M: Y˛ )˛%in a PICT to corresponding PostScript ° d ONLN d
Y < e u ( Å Z operations. ° d ONLN d Y u e˛ )9MTo get a feel for this conversion, you can analyze the PostScript dump from a ° d ONLN dg e < q¬ ( ç ZKLaserWriter to see how it converts a PICT to PostScript. Under System 6.x, ° d ONLN d≤ e¬ q˛ ( ç‡ a PostScript ° d ONLN dø q < } ( ô ZUdump can be obtained by pressing Command-K while printing. Under System 7.0, you can ° d ONLN d q }˛ ( ôget ° d ONLN d } < âp ( • ZCa dump by selecting the PostScript File option in the Print dialog. ° d ONLN d\ ï < °ı *NSome areas of QuickDraw, such as transfer modes, do not have a correspondence ° d ONLN d™ ïı °˛ ( Ωin ° d ONLN d≠ ° < ≠â ( … ZGPostScript. The PostScript imaging model is designed so that all areas ° d ONLN dÙ °â ≠˛ ( …ßof a page affected by an ° d ONLN d
≠ < π n ( ’ Z
image are ° d ONLN d ≠ n π˛ )2Lmarked as if with opaque paint. Using image masks can help. See the Graphics ° d ONLN dd π < ≈ ( · Z+chapter in the PostScript reference manual. ° d ONLN dê — < › *,PICT-to-PostScript conversion can be a long ° d ONLN dº — ›˛ )„-process, especially if one is unfamiliar with ° d ONLN dÍ › < È ¯ ( Z&PostScript. Using the above books and ° d ONLN d › ¯ È˛ )º2the PostScript dump from the LaserWriter (but ONLY ° d ONLN dC È < ı “ ( Z as a general guide) should help.
° d ONLN dd
< D *''Calling InitCursor instead of SetCursor
° d ONLN då <( b * Written: ° d ONLN dï à( ≤ )L10/23/90 ° d ONLN dû( <4 Å (P ZLast reviewed: ° d ONLN d≠( à4 ¨ )L2/20/91 ° d ONLN dµ@ <Lè (h ZGIs it legal to call InitCursor instead of SetCursor(arrow) when I want ° d ONLN d¸@èL˛ (h≠to set the cursor to an ° d ONLN dL <X å (t Zarrow (after my ° d ONLN d$L åX˛ )PInormal one-time program initialization code, in my UpdateCursor routine)? ° d ONLN dnX <dI (Ä Z6The only reason I'd want to do such a skanky thing is ° d ONLN d§XId˛ (Äg$to save code. Calling a trap with no ° d ONLN d…d <p í (å Zparameters is less ° d ONLN d‹d íp˛ )VJcode than one with parameters. What, exactly, if anything, does InitCursor ° d ONLN d'p <|§ (ò ZOdo besides setting the cursor to an arrow and setting the cursor level to zero? ° d ONLN dw| <à N * ___ ° d ONLN d{î <†U *8There's no problem at all with this, as long as you are ° d ONLN d≥îU†˛ (ºs aware that the hidden, busy, and ° d ONLN d‘† <¨ Ÿ (» Z!obscured states are cleared when ° d ONLN dı† Ÿ¨˛ )ù<you call InitCursor, so if the cursor was hidden or obscured ° d ONLN d2¨ <∏A (‘ Z:for good reason it'll suddenly reappear. It also gets the ° d ONLN dl¨A∏˛ (‘_$arrow from QuickDraw, of course, but ° d ONLN dë∏ <ƒ û (‡ Zthat's not a problem.
° d ONLN dß‹ <Î ◊ *'PICT fontName opcode
° d ONLN dºÎ <˜ b * Written: ° d ONLN d≈Î à˜ ≤ )L10/31/90 ° d ONLN dŒ˜ < Å ( ZLast reviewed: ° d ONLN d›˜ à ¨ )L2/20/91 ° d ONLN d <¡ (7 ZRIs there an up-to-date canonical source for PICT opcodes? In “Night of the Living ° d ONLN d7¡˛ (7fl
Disc,” as far ° d ONLN dE <'I (C Z6as I can see, the only list of PICT opcodes is in the ° d ONLN d{I'˛ (Cg Macintosh Tech Note “QuickDraw’s ° d ONLN dú' <3√ (O ZPInternal Picture Definition” which does not mention opcode $2C. It appears that ° d ONLN dÏ'√3˛ (O·
opcode $2C ° d ONLN d˜3 <?Ù ([ ZRconcerns font names. I recall seeing a patch for PictDetective named "fontnameop" ° d ONLN d I3Ù?˛ ([or ° d ONLN d L? <K≠ (g ZMsomething like that. However I can't be sure that $2C is the only new opcode. ° d ONLN d öK <W N * ___ ° d ONLN d ûc <oÜ *@The fontName opcode is documented in the Technical Note “32-Bit ° d ONLN d ficÜo˛ (ã§QuickDraw: Version 1.2 ° d ONLN d ıo <{fi (ó ZXFeatures.” Note also that since the introduction of 32-Bit QuickDraw there are two more ° d ONLN d
Mofi{˛ (ó¸bitmap ° d ONLN d
T{ <áÏ (£ ZQopcodes for direct RGB PixMaps $009A (DirectBitsRect) and $009B (DirectBitsRgn). ° d ONLN d
≥á vì˛ ):Nsection of Inside Macintosh Volume VI has all these opcodes listed in a single ° d ONLN d ì <ü√ (ª ZRplace, making it easier to get the necessary info. Here is the info on font names ° d ONLN d Tì√ü˛ (ª· and pictures ° d ONLN d aü <´ (« Z)from the "32-Bit QuickDraw..." Tech Note: ◊ X◊
° d ONLN d ) 5 “ *$#PICTs Contain Font Name Information ° d ONLN d $ A M~ *JEvery time you draw text inside of an _OpenPicture and _ClosePicture pair, ° d ONLN d o M YÉ * KQuickDraw stores the name of the current font and uses it when playing back ° d ONLN d ª Y eÉ * Nthe picture. The opcode used to save this information is $002C and its data is ° d ONLN d
e q L * as follows: ,
Courier
° d ONLN d } à ê * PictFontInfo = Record ° d ONLN d/ á ív *
F length : Integer; { length of data in bytes } ° d ONLN dv ë úv *
F fontID : Integer; { ID in the source system } ° d ONLN dΩ õ ¶ ÷ *
& fontName : Str255; ° d ONLN d‰ • ∞ Ü *
END;
° d ONLN d˚ ª «á *EQuickDraw saves this information only one time for each font used in ° d ONLN d@ ªá «⁄ ( „•a picture. When ° d ONLN dP « ”X ( Ô 6BQuickDraw plays back a picture, it uses the fontID as a reference ° d ONLN dí «X ”⁄ ( Ôvinto the list of font names ° d ONLN dÆ ” fl* ( ˚ 6<which are used to set the correct font on the target system. ° d ONLN dÎ Î ˜ µ * For example, the following code:
° d ONLN d q *E GetFNum('Venice', theFontID); { Set a font before opening PICT} ° d ONLN dR
ã *
TextFont(theFontID); ° d ONLN dj! , Ã *$ pHand2 := OpenPicture (pictRect); ° d ONLN dè+ 6 Å *
MoveTo(20,20); ° d ONLN d•5 @ € *
' DrawString(' Better be Venice'); ° d ONLN dÕI T Ã *$ GetFNum('Geneva', theFontID); ° d ONLN dÚS ^ ü *
TextFont(theFontID); ° d ONLN d] h Å *
MoveTo(20,40); ° d ONLN d$g r § *
DrawString('Geneva'); ° d ONLN dA{ Ü ÷ *& GetFNum('New York', theFontID); ° d ONLN dhÖ ê ü *
TextFont(theFontID); ° d ONLN dÑè ö Å *
MoveTo(20,60); ° d ONLN döô § Æ *
DrawString('New York'); ° d ONLN dπ≠ ∏ Ã *$ GetFNum('Geneva', theFontID); ° d ONLN dfi∑ ¬ ü *
TextFont(theFontID); ° d ONLN d˙¡ Ã Å *
MoveTo(20,80); ° d ONLN dÀ ÷ § *
DrawString('Geneva'); ° d ONLN d-’ ‡ h *
ClosePicture;
° d ONLN d>Î ˜ *:generates a picture containing font information like this:
° d ONLN dy | * OpCode 0x002C {9, ° d ONLN dé
q *
E "0005 0656 656E 6963 65"} /* save current font */ ° d ONLN d‘ " r *
TxFont 'venice' ° d ONLN dÁ! , Â *
) DHDVText {20, 20, " Better be Venice"} ° d ONLN d+ 6q *
E OpCode 0x002C {9, /* save next font name */ ° d ONLN dW5 @ ∏ *
"0003 0647 656E 6576 61"} ° d ONLN dx? J r *
TxFont 'geneva' ° d ONLN dãI T ê *
DVText {20, "Geneva"} ° d ONLN d§S ^v *
F OpCode 0x002C {11, /* ditto */ ° d ONLN dÎ] h — *
% "0002 084E 6577 2059 6F72 6B"} ° d ONLN dg r w *
TxFont 'newYork' ° d ONLN d%q | ö *
DVText {20, "New York"} ° d ONLN d@{ Üg *
C TxFont 'geneva' /* second Geneva does not ° d ONLN dÑÖ êg *
. +Z-Developer Support Center ( -Ê October 1992 / X /
° d ONLN d < )… ( E ZVThis feature works regardless of the type of picture being saved, including old style ° d ONLN d V … )˛ ( EÁ
PICTs in a ° d ONLN d a ) < 5S ( Q Z5black-and-white port. Using _OpenCPicture instead of ° d ONLN d ñ )S 5˛ ( Qq!_OpenPicture to start a recording ° d ONLN d ∏ 5 < A ˚ ( ] Z*session results in the same functionality. ° d ONLN d „ M < Y b *X-Refs: ° d ONLN d Î Y < e ƒ * Inside Macintosh Volume VI ° d ONLN d e < qÄ * BMacintosh Technical Note “QuickDraw's Internal Picture Definition” ° d ONLN dI q < }Ñ * AMacintosh Technical Note “32-Bit QuickDraw: Version 1.2 Features”
° d ONLN dã ï < § *' Using PicComments to rotate text
° d ONLN d¨ § < ∞ b * Written: ° d ONLN dµ § à ∞ ≤ )L11/28/90 ° d ONLN dæ ∞ < º Å ( ÿ ZLast reviewed: ° d ONLN dÕ ∞ à º ≤ )L12/19/90 ° d ONLN d÷ » < ‘ ( Z\I have a PostScript routine (using TextBegin/TextEnd) to generate bitmapped rotated text on ° d ONLN d2 » ‘˛ ( the ° d ONLN d6 ‘ < ‡ Å ( ¸ Zscreen (which ° d ONLN dD ‘ Å ‡˛ )EOcan be later printed on QuickDraw printers). Why do I get duplicate text? I get ° d ONLN dî ‡ < Ï* ( Z3both bitmapped rotated text and PostScript rotated ° d ONLN d« ‡* Ï˛ )Ó,text when I print on the LaserWriter II, and ° d ONLN dÙ Ï < ¯Ö ( ZDboth bitmapped rotated text and horizontal text on the ImageWriter. ° d ONLN d8 ÏÖ ¯˛ (£When I make a machine ° d ONLN dN ¯ < o ( Z
dependent ° d ONLN dX ¯ o˛ )3Tcheck (check type of printer) and call the proper printing procedure, it works fine. ° d ONLN d≠ <5 (, Z/Because of the speed and memory considerations ° d ONLN d‹5˛ )˘(of generating the rotated bitmapped text ° d ONLN d < — (8 Z[(especially at 300 dpi), is there a way to ensure that the printer will use the PostScript ° d ONLN d`— ˛ (8ÔBEFORE ° d ONLN dg <( ¶ (D Zgenerating the bitmap? ° d ONLN d~( <4 N * ___ ° d ONLN dÇ@ <L z * We will use ° d ONLN dé@ zL˛ )>Ithe following Macintosh PicComments to hide your QuickDraw calls from the ° d ONLN dÿL <X (t Z/LaserWriter, but the ImageWriter will use them: ,
Courier
° d ONLN dd <o á *PostScriptBegin ° d ONLN dn <yw *
? >> Put your CopyBits and QuickDraw calls to image your rotated ° d ONLN dXx <É √ *
>> bitmapped text here.... ° d ONLN dtÇ <ç } *
PostScriptEnd
° d ONLN dÇò <§ ® *By wrapping your ° d ONLN dìò ®§˛ )l;QuickDraw code within the PostScriptBegin and PostScriptEnd ° d ONLN dœ§ <∞€ (à ZSPicComments, the code will be ignored by the LaserWriter, but the ImageWriter will ° d ONLN d"§€∞˛ (Ã˘use the ° d ONLN d*∞ <º (ÿ ZSQuickDraw calls. Basically, the PostScriptBegin and PostScriptEnd PicComments tell ° d ONLN d}∞º˛ (ÿthe ° d ONLN dź <»Ô (‰ ZZLaserWriter driver to turn “off” QuickDraw. In the ImageWriter case, the ImageWriter does ° d ONLN d€ºÔ»˛ (‰
not ° d ONLN dfl» <‘¨ ( ZJunderstand the PicComments. Therefore, it will use the QuickDraw calls to ° d ONLN d)»¨‘˛ ( create and image ° d ONLN d:‘ <‡ û (¸ Zyour bitmapped text. ° d ONLN dPÏ <¯! *-Now, we need to use the rotation PicComments ° d ONLN d}Ï!¯˛ )Â/to rotate the text on the LaserWriter, but have ° d ONLN d≠¯ < ÷ ( Z the ImageWriter ignore the code:
° d ONLN dŒ < á *Rect zeroRect; ° d ONLN dfi$ </ ‹ * SetRect (&zeroRect, 0, 0, 0, 0); ° d ONLN dˇ8 <C i * TextBegin ° d ONLN d B <M n *
TextCenter ° d ONLN dL <W √ *
ClipRect (&zeroRect); ° d ONLN d0` <kh *< >> Draw your text to be rotated on the LaserWriter.... ° d ONLN dmt < » * ClipRect (&rPageRect); ° d ONLN dä~ <â _ *
TextEnd
° d ONLN díî <†‘ *XWrapping your text drawing call(s) between the ClipRect calls will ensure that the text ° d ONLN dÍ˛ (ºÚis drawn ° d ONLN dÛ† <¨Û (» ZVonly on the LaserWriter. Setting the ClipRect to zero tells the ImageWriter to ignore ° d ONLN d I†Û¨˛ (»all ◊ X◊
° d ONLN d ) ö *QuickDraw calls until the ° d ONLN d ö )⁄ )Ç@ClipRect is reset to something “real” (actually, a zero ClipRect ° d ONLN d [ ) 5 ô ( Q 6prevents QuickDraw from ° d ONLN d s ) ô 5⁄ )Å>drawing anything). After we have completed drawing the rotated ° d ONLN d ≤ 5 A £ ( ] 6 text, we reset the ClipRect to ° d ONLN d — 5 £ A⁄ )ãAthe dimensions of rPage (that is, rPage is the image-able area of ° d ONLN d A MJ ( i 6@the currently selected printer—see Inside Macintosh, Volume II, ° d ONLN dS AJ M⁄ ( ih page 150). This will allow all ° d ONLN dr M Y b ( u 6of your normal ° d ONLN dÅ M b Y⁄ )JLdrawing to continue on the ImageWriter and LaserWriter. If you did not reset ° d ONLN dŒ Y e ÿ ( Å 6%the ClipRect after the TextEnd call, ° d ONLN dÛ Y ÿ e⁄ )¿,nothing would be drawn on the ImageWriter or ° d ONLN d e q T ( ç 6 LaserWriter.
° d ONLN d- â òO *'*Using dithered drawing mode with QuickDraw
° d ONLN dX ò § > * Written: ° d ONLN da ò d § é )L11/28/90 ° d ONLN dj § ∞ ] ( à 6Last reviewed: ° d ONLN dy § d ∞ é )L12/19/90 ° d ONLN dÇ º »Æ ( ‰ 6NWhen I draw a 32-bit Macintosh PICT image from a file to an 8-bit port via an ° d ONLN d– ºÆ »⁄ ( ‰Ã offscreen ° d ONLN d⁄ » ‘ ( 67GWorld, I use dither mode in the CopyBits call and the ° d ONLN d » ‘⁄ ( >)results are quite impressive. If there is ° d ONLN d; ‘ ‡o ( ¸ 6Dnot enough memory to allocate the GWorld, I draw the image directly ° d ONLN d ‘o ‡⁄ ( ¸çto the port. But since ° d ONLN dñ ‡ Ï ⁄ ( 6*there does not seem to be any way to tell ° d ONLN d¿ ‡ ⁄ Ï⁄ )¬1QuickDraw to use dithered drawing mode, the image ° d ONLN dÚ Ï ¯ ^ ( 6looks horrible. ° d ONLN d ( *9Do you have any suggestions? I have installed bottleneck ° d ONLN d;(⁄ (,F%procs to allow DrawPicture to get its ° d ONLN da € (8 6,data from the file instead of the handle in ° d ONLN dç € ⁄ )√4memory. Is there a way, while in the bottlenecks, to ° d ONLN d¬ ( — (D 6'find the CopyBits call that comes from ° d ONLN dÈ —(⁄ )π8the picture and force it to use dithered mode instead of ° d ONLN d"( 4o (P 6Bsource mode? I don’t want to try and parse the PICT myself, but I ° d ONLN dd(o4⁄ (Pçthought that maybe a ° d ONLN dy4 @ ë (\ 6QuickDraw global could ° d ONLN dê4 ë@⁄ )yAbe modified in my StdBits proc to force dithered drawing for that ° d ONLN d“@ L a (h 6operation only? ° d ONLN d‚L X * * ___ ° d ONLN dÊd pà *^You can install a StdBits or bitsProc bottleneck procedure to get all the CopyBits calls when ° d ONLN dDdÃp⁄ (åÍthe ° d ONLN dHp |{ (ò 6Kpicture is being played back. One of the parameters to the StdBits call is ° d ONLN dìp{|⁄ (òôthe mode. You can ° d ONLN d•| à 8 (§ 6install ° d ONLN d≠| 8à⁄ ) Sa procedure that saves the current mode, and then passes ditherMode to the original ° d ONLN dà îï (∞ 6PStdBits proc. This is all you should need to do. It’s been done here so we know ° d ONLN dQàïî⁄ (∞≥it works, only ° d ONLN d`î †Q (º 6Dnot in any form that can be sent to you as sample code at this time.
° d ONLN d•∏ «9 *'(Code for reversing Macintosh PICT images
M{ The scan line is simply an array [0..RowBytes] of Byte, and since this is } ° d ONLN d ˝ <, *
0{ 8 bits per pixel, each one is a single pixel.} ° d ONLN dN < √ *
Size:=thePixMap^.RowBytes; ° d ONLN dj < ‹ *
For Index:=0 to (Size div 2) do ° d ONLN dã <& _ *
begin ° d ONLN dì% <0 Î *
# tempPixel:=ThisScanLine^[Index]; ° d ONLN d∑/ <:@ *
4 ThisScanLine^[Index]:=ThisScanLine[Size-Index-1]; ° d ONLN dÏ9 <D Î *
# ThisScanLine^[Index]:=tempPixel; ° d ONLN dC <N Z *
end; ° d ONLN dM <X P *
end;
° d ONLN d c <o ¬ *This same procedure can be ° d ONLN d7c ¬o˛ )ÜAused also to swap a 1-, 2- or 4-bit-per-pixel pixmap if you add a ° d ONLN dyo <{9 (ó Z8function that accepts a byte and swaps the pixels in it.
° d ONLN d≤ì <¢ª *'7Use srcOr instead of srcCopy for Macintosh text drawing
° d ONLN dÍ¢ <Æ b * Written: ° d ONLN dÛ¢ àÆ ¶ )L6/4/91 ° d ONLN d˙Æ <∫ Å (÷ ZLast reviewed: ° d ONLN d Æ à∫ ¨ )L10/9/91 ° d ONLN dΔ <“= (Ó Z1DrawText with srcCopy takes six times as long as ° d ONLN dBΔ=“˛ (Ó[#with srcOr now that my Macintosh is ° d ONLN df“ <fiw (˙ ZArunning System 7. Why is this so slow? Is this a bug in System 7? ° d ONLN d®fi <Í N * ___ ° d ONLN d¨ˆ < Æ *It’s true that srcCopy is ° d ONLN dΔˆ Æ˛ )rDslower than srcOr when handling text, especially in color mode. This ° d ONLN d < (* Z&loss in speed occurs because CopyBits ° d ONLN d1˛ )Δ2is a lot smarter than it used to be. It can handle ° d ONLN dd <® (6 ZLforeground and background colors a lot better, but that improvement came at ° d ONLN d∞®˛ (6Δthe cost of speed. ° d ONLN d√ <&= (B Z4Our recommended method for drawing text is to erase ° d ONLN d˜=&˛ (B[&before drawing, and use srcOr to draw, ° d ONLN d & <2‘ (N ZSnot srcCopy. Alternatively, you could draw colorized text in srcOr mode off screen ° d ONLN dq&‘2˛ (NÚand then ° d ONLN dz2 <>¶ (Z ZKuse CopyBits to draw it on the screen in srcCopy mode without colorization.
° d ONLN dΔV <e> *'%Techniques for graying Macintosh text
° d ONLN dÏe <q b * Written: ° d ONLN dıe àq ¶ )L6/3/91 ° d ONLN d¸q <} Å (ô ZLast reviewed: ° d ONLN d q à} ¶ )L8/1/91 ° d ONLN dâ <ïÅ (± ZBHow do I draw grayed-out text on the Macintosh, like the text for ° d ONLN dTâÅï˛ (±üdisabled buttons or menu ° d ONLN dmï <° Z (Ω Zitems? ° d ONLN dt° <≠ N * ___ ◊ X◊
° d ONLN d ) 5U *$FThere are currently two different kinds of grayed text: First, there’s ° d ONLN d H 5 A ƒ * $“patterned” gray, where every other ° d ONLN d l 5 ƒ A⁄ )¨8dot is missing. This really only looks good with Chicago ° d ONLN d • A M- ( i 65or other heavy fonts and was always used for graying ° d ONLN d ⁄ A- M⁄ ( iK out menus and controls in system ° d ONLN d ˚ M Y ( u 66software through 6.0.x, and is still used in 7.0 when ° d ONLN d1 M Y⁄ )˝+the screen is set to less than 4 bits deep. ° d ONLN d] Y e ∞ ( Å 6 This is done by first drawing ° d ONLN d{ Y ∞ e⁄ )ò8the text in a normal, srcCopy transfer mode. Then a gray ° d ONLN d¥ e q q ( ç 6rectangle is drawn ° d ONLN d« e q q⁄ )YMover the text using the patBic mode. This “erases” half the bits in the text, ° d ONLN d q } ( ô 6:and is rapid enough that there is very rarely any flicker. ° d ONLN dP â ï( *<The second kind of text is the actually gray text, which is ° d ONLN då â( ï⁄ ( ±F$used in System 7 on screens that are ° d ONLN d± ï °Ñ ( Ω 6J4 bits deep or deeper for menus, controls, and other grayed text. To draw ° d ONLN d˚ ïÑ °⁄ ( Ω¢this text, just call ° d ONLN d ° ≠Ñ ( … 6HGetGray (as documented on page 17-27 of Inside Macintosh, Volume VI) to ° d ONLN dX °Ñ ≠⁄ ( …¢get an appropriate ° d ONLN dk ≠ π À ( ’ 6'gray. Then draw the text in that color.
° d ONLN dì — ‡Ñ *'3Updating Macintosh cursor without mouse competition
° d ONLN d« ‡ Ï > * Written: ° d ONLN d– ‡ d Ï à )L6/12/91 ° d ONLN dÿ Ï ¯ ] ( 6Last reviewed: ° d ONLN dÁ Ï d ¯ Ç )L8/1/91 ° d ONLN dÓ (, 6WHow can I programmatically move the Macintosh mouse without the real mouse interfering? ° d ONLN dF * * ___ ° d ONLN dJ( 4q *GThe real answer to your question is twofold: First, you can do exactly ° d ONLN dë(q4⁄ (Pèwhat you want to do ° d ONLN d•4 @d (\ 6Bwith the sample included below. HOWEVER, this is not a good thing ° d ONLN dÁ4d@⁄ (\Çto do, it would be better ° d ONLN d@ L O (h 6 if you took ° d ONLN d
@ OL⁄ )7Othe solution used in Apple’s Guided Tour disks: Always hide the cursor and then ° d ONLN d]L X Á (t 6*decouple the cursor from the mouse. Then, ° d ONLN dáL ÁX⁄ )œ1instead of using the system’s cursor, simply draw ° d ONLN dπX d (Ä 64your own “cursor” using QuickDraw and treat it as a ° d ONLN dÌXd⁄ )˚*little animated bitmap on the screen. This ° d ONLN dd p (å 6/avoids all the problems that you have with the ° d ONLN dGdp⁄ )Ì'mouse competing. (Apple does update the ° d ONLN dop |ã (ò 6Omouse globals with the mouse position so that other things function correctly.) ° d ONLN døà î≠ *PNow, as promised, here is the way to do what you want using the real cursor. As ° d ONLN dà≠î⁄ (∞Àyou have ° d ONLN dî † (º 65discovered, setting the crsrCouple variable to false ° d ONLN dMî†⁄ )ˇ&prohibits the mouse from affecting the ° d ONLN dt† ¨B (» 6?cursor; unfortunately, it also prohibits the jcrsrTask routine ° d ONLN d≥†B¨⁄ (»` from drawing the cursor. The ° d ONLN d–¨ ∏ ‰ (‘ 60solution to this is to set crsr couple to true, ° d ONLN d ¨ ‰∏⁄ )Ã3call the cursor drawing routine jCrsrTask yourself, ° d ONLN d4∏ ƒ< (‡ 6>and then set the crsrCouple variable to false, as shown below: ,
Courier
° d ONLN ds– € w *procedure callcrsr; ° d ONLN dá⁄ Â Â *
° d ONLN dÕ; <G b * Written: ° d ONLN d÷; àG ¨ )L11/6/91 ° d ONLN dfiG <S Å (o ZLast reviewed: ° d ONLN dÌG àS ¨ )L11/6/91 ° d ONLN dı_ <k~ (á ZBDo you have an example of flicker-free animation on the Macintosh? ° d ONLN d8k <w N * ___ ° d ONLN d<É <è *'We have some good stuff that’s written ° d ONLN dcÉè˛ )“(in MPW Pascal. It’s DTS Sample Code #16, ° d ONLN dåè <õ v (∑ Z OffSample, ° d ONLN dóè võ˛ ):Land this uses some routines defined in DTS Sample Code #15, OffScreen. Also, ◊ X◊
° d ONLN d )v *Fthe System 7.0 CD sample code folder contains a smaller sample called ° d ONLN d F v )⁄ ( Eî“GMonde” that uses ° d ONLN d Y ) 5 H ( Q 6GWorlds.
° d ONLN d b M \ ‚ *'CopyBits bug and workaround
° d ONLN d ~ \ h > * Written: ° d ONLN d á \ d h à )L6/26/91 ° d ONLN d è h t ] ( ê 6Last reviewed: ° d ONLN d û h d t à )L8/13/91 ° d ONLN d ¶ Ä åß ( ® 6UHas anyone run across what I’m told is a bug in CopyBits? It works like this: In the ° d ONLN d ˚ Äß å⁄ ( ®≈
deep, dark ° d ONLN d å ò • ( ¥ 6workings of CopyBits, some ° d ONLN d! å • ò⁄ )ç@routine tries to read the two bytes preceding the baseAddress of ° d ONLN db ò § ( ¿ 66the source PixMap. If the baseAddress is at the start ° d ONLN dò ò §⁄ )¯)of a card’s NuBus space and there isn’t a ° d ONLN d¬ § ∞’ ( à 6]card filling the adjacent space, this causes a bus error! Has anyone found a good workaround? ° d ONLN d ∞ º * * ___ ° d ONLN d$ » ‘≥ *SThe short answer is: you’re right. QuickDraw inadvertently reads from memory below ° d ONLN dw »≥ ‘⁄ ( —the base ° d ONLN dÄ ‘ ‡¿ ( ¸ 6Yaddress of a pixmap. The workaround is to place the video base address 32 bytes into the ° d ONLN dŸ ‘¿ ‡⁄ ( ¸fiRAM ° d ONLN d› ‡ Ï ( 68on the card; if the card you’re using doesn’t have this ° d ONLN d ‡ Ï⁄ )˛&workaround, there’s nothing you can do ° d ONLN d< Ï ¯1 ( 6=other than making sure there’s a card in the next-lower slot.
° d ONLN dz D *'+Macintosh picture (PICT) 90-degree rotation
° d ONLN d¶ + > * Written: ° d ONLN dØ d+ à )L7/23/91 ° d ONLN d∑+ 7 ] (S 6Last reviewed: ° d ONLN dΔ+ d7 à )L8/30/91 ° d ONLN dŒC O } (k 6The trick for rotating ° d ONLN dÂC }O⁄ )eHa Macintosh QuickDraw picture 90 degrees is to intercept all bottlenecks ° d ONLN d.O [¢ (w 6Tand exchange the x and y coordinates. Then, call OpenPicture to receive the rotated ° d ONLN dÇO¢[⁄ (w¿
picture, call ° d ONLN dê[ g, (É 6:DrawPicture(unrotatedPicture), and then call ClosePicture ° d ONLN d [,g⁄ (ÉJ$on the rotated picture. You’re done! ° d ONLN dÔg s m (è 6QuickDraw spins ° d ONLN dˇg ms⁄ )UJout the DrawPicture call into its component parts, but runs each component ° d ONLN dJs ‡ (õ 6+through the bottlenecks first, so they get ° d ONLN dus ‡⁄ )»1rotated (by YOUR bottleneck intercepts) and stuck ° d ONLN dß ã ≈ (ß 6&into the new picture, already rotated. ° d ONLN dŒó £S *>Here‘s a bottleneck intercept for StdLine that rotates a PICT ° d ONLN d óS£⁄ (øqcomposed entirely of Line ° d ONLN d&£ Ø (À 64commands (which depend on the current pen position): ,
Courier
° d ONLN d[ª Δ « *#procedure MyLineProc(newPt: point); ° d ONLN d≈ – ' *
var ° d ONLN dÉœ ⁄ r *
tempV : integer; ° d ONLN dñŸ ‰ 1 *
begin ° d ONLN dú„ Óä *
J tempV := thePort^.pnLoc.v; { Swap current pen location coordinates } ° d ONLN dÁÌ ¯ € *
' thePort^.pnLoc.v := thePort^.pnLoc.h; ° d ONLN d˜ § *
thePort^.pnLoc.h := tempV; ° d ONLN d/ ä *J tempV := newPt.v; { Swap destination pen location coordinates } ° d ONLN dz Å *
newPt.v := newPt.h; ° d ONLN dê * w *
newPt.h := tempV; ° d ONLN dß3 > m * StdLine(newPt); ° d ONLN dºG Rä *J tempV := thePort^.pnLoc.v; { Restore current pen location coordinates } ° d ONLN dQ \ € *
' thePort^.pnLoc.v := thePort^.pnLoc.h; ° d ONLN d/[ f § *
thePort^.pnLoc.h := tempV; ° d ONLN dLe p , *
end;
° d ONLN dQ{ á ” **Notice that the start coordinates as well ° d ONLN d{{ ”á⁄ )ª5as the destination coordinates must be swapped before ° d ONLN d±á ìZ (Ø 6Bcalling StdLine. The resulting pen location is swapped back again ° d ONLN dÛáZì⁄ (Øxafter the operation, so the ° d ONLN d ì ü@ (ª 6?port looks like it should if unrotated drawing were performed. ° d ONLN d Nì@ü⁄ (ª^ For things that don’t depend on ° d ONLN d nü ´ (« 6=the current pen location, things are simplified a little bit. ◊ 4◊˘
*%10 )
of 22 (ÏñBasic QuickDraw Q&As ˇ
Ä ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +Z-Developer Support Center ( -Ê October 1992 / X /
° d ONLN d ) < 5— ( Q ZRYou’ll still need bitmap rotation code for the StdBits and StdText intercepts.You ° d ONLN d R )— 5˛ ( QÔmight do ° d ONLN d [ 5 < Aí ( ] ZLStdText by setting the port to an offscreen one you create earlier, calling ° d ONLN d ß 5í A˛ ( ]∞QuickDraw’s StdText, ° d ONLN d º A < Më ( i ZKand then calling your bitmap rotation code to copy it into the destination.
° d ONLN d e < t° *'3Macintosh QuickDraw and pen characteristic routines
° d ONLN d< t < Ä b * Written: ° d ONLN dE t à Ä ¨ )L8/12/91 ° d ONLN dM Ä < å Å ( ® ZLast reviewed: ° d ONLN d\ Ä à å ¨ )L11/6/91 ° d ONLN dd ò < §" ( ¿ Z-When generating pictures and then looking at ° d ONLN dë ò" §˛ )Ê)the corresponding Macintosh PICT file, we ° d ONLN dª § < ∞v ( à Z?notice that QuickDraw is optimizing PnMode, PnPat, and PnSize. ° d ONLN d˙ §v ∞˛ ( ÃîCan you tell us how to stop ° d ONLN d ∞ < º∂ ( ÿ ZHQuickDraw from optimizing, and how to know when QuickDraw will optimize? ° d ONLN d_ º < » N * ___ ° d ONLN dc ‘ < ‡≥ *NQuickDraw does not optimize away new pen characteristic routines, but it does ° d ONLN d± ‘≥ ‡˛ ( ¸—insert them into ° d ONLN d¬ ‡ < Ï d ( Z pictures ° d ONLN dÀ ‡ d Ï˛ )(Ujust before a drawing routine that uses the pen rather than place them where they are ° d ONLN d! Ï < ¯‘ ( ZVcalled. Therefore, you may not see your new pen characteristic routine until later in ° d ONLN dw Ï‘ ¯˛ (Ú a picture ° d ONLN dÅ ¯ < ñ ( Zwhen it is about to ° d ONLN dï ¯ ñ˛ )ZKbe used. Opcodes for pen characteristics are inserted into the picture when ° d ONLN d· <: (, Z5they are changed from the previous time they’re used.
° d ONLN d( <7∫ *'8Detecting whether application window is partially hidden
° d ONLN dP7 <C b * Written: ° d ONLN dY7 àC ¨ )L9/26/92 ° d ONLN daC <O Å (k ZLast reviewed: ° d ONLN dpC àO ¨ )L1/27/92 ° d ONLN dx[ <g# (É Z3We draw directly to the screen to gain the fastest ° d ONLN d´[#g˛ )Á*possible animation speed, and when we need ° d ONLN d÷g <s ˜ (è Z#compatibility—such as when windows ° d ONLN d˘g ˜s˛ )ª3overlap or for multiple screens—we do use CopyBits. ° d ONLN d-s <Ÿ (õ ZXHow do we tell whether the window is hidden or that the visible part is not rectangular? ° d ONLN dÜ <ã N * ___ ° d ONLN däó <£ ï *If your window is ° d ONLN dúó ï£˛ )YJcovered partially by another applications window or if your layer has been ° d ONLN dÁ£ <Ø≥ (À ZJhidden by the process menu, the visRgn of your window’s grafport will not ° d ONLN d1£≥Ø˛ (À—be the portRect ° d ONLN dAØ <ª m (◊ Z anymore. ° d ONLN dJØ mª˛ )1P(Keep in mind that if you scroll by modifying the portRect of the grafport, then ° d ONLN dõª <«O („ Z;you’ll have to do a more complex calculation...) Here is a ° d ONLN d÷ªO«˛ („m&small Pascal routine that returns this ° d ONLN d˝« <” v (Ô Z information: ◊ X◊
*˝Basic QuickDraw Q&As (Ï˙11 )
of 22 ˇ
fi ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘ ,
Courier
° d ONLN d ) 4 ˛ *#.Function UseCopyBits(thePort:grafptr):Boolean; ° d ONLN d / = H 1 *begin ° d ONLN d 9 Q \: *: UseCopyBits:= NOT( (thePort^.VisRgn^^.rgnSize=10) and ° d ONLN d t [ f0 *
8 (thePort^.visRgn^^.RgnBBox=thePort^.PortRect) ); ° d ONLN d ≠ e p , *
end; ° d ONLN d ≤ y Ñè *KThe rect strucRgn^^.rgnBBox will be zero for a visible window if the system ° d ONLN d ˇ É é ü *
has hidden the application.
° d ONLN d • ¥> *&,How to tell whether GetPictInfo is available
° d ONLN dH ¥ ¿ > * Written: ° d ONLN dQ ¥ d ¿ é )L12/16/91 ° d ONLN dZ ¿ à ] ( Ë 6Last reviewed: ° d ONLN di ¿ d à à )L2/24/92 ° d ONLN dq ÿ ‰ W ( 6 How do you ° d ONLN d| ÿ W ‰⁄ )?Pdetermine whether the function GetPictInfo is available? Gestalt doesn’t seem to ° d ONLN dÕ ‰ z ( 6have the right stuff?! ° d ONLN d‰ ¸ * * ___ ° d ONLN dË *0To determine whether the GetPictInfo routine is ° d ONLN d⁄ )Î*available, check the system version number ° d ONLN dC ∑ (< 6Vwith the Gestalt function. The GetPictInfo routine is available under system software ° d ONLN dô∑ ⁄ (<’version ° d ONLN d° , t (H 67.0 and later. Use ° d ONLN d¥ t,⁄ )\Ithe Gestalt selector gestaltSystemVersion to determine the version of the ° d ONLN d˛, 8A (T 6>system currently running. In most cases you shouldn’t rely on ° d ONLN d<,A8⁄ (T_ the system version to determine ° d ONLN d\8 D ˘ (` 62if features are available. However, in this case, ° d ONLN dé8 ˘D⁄ )·0this is the only way to determine if the Picture ° d ONLN døD P ¢ (l 6 Utilities Package is available. ° d ONLN dfl\ hú *JSee Inside Macintosh Volume VI page 3-42 for information on using Gestalt ° d ONLN d)\úh⁄ (Ñ∫ to check the ° d ONLN d6h t6 (ê 66System version number. See Inside Macintosh Volume VI ° d ONLN dlh6t⁄ (êT page 18-3 for information on the ° d ONLN dçt Ä è (ú 6Picture Utilities Package. ° d ONLN d®å ò∂ *ZFor example, the following C function will determine if the GetPictInfo call is available:
° d ONLN d§ Ø ü * #include <GestaltEQU.h> ° d ONLN d ∏ √ ∏ * Boolean IsGetPictInfoAvail() ° d ONLN d@¬ Õ 1 *
{ ° d ONLN dFÃ ◊ h *
OSErr err; ° d ONLN dW÷ · w *
long feature; ° d ONLN dkÍ ı& *6 err = Gestalt(gestaltSystemVersion,&feature); ° d ONLN d¢˛ Ù *, /*-- check for system 7 and above --*/ ° d ONLN dœ — *
% return (feature >= 0x00000700); ° d ONLN dı 1 *
} ° d ONLN d˚& 1 ï *or, if you prefer Pascal: ° d ONLN d: E Â *) function IsGetPictInfoAvail: Boolean; ° d ONLN d?D O ; *
var ° d ONLN dGN Y w *
err: OSErr; ° d ONLN d[X c ï *
feature: longint; ° d ONLN dub m E *
begin ° d ONLN dl w& *
6 err := Gestalt(gestaltSystemVersion, feature); ° d ONLN d∂v Å ˛ *
. (*-- check for system 7 and above --*) ° d ONLN dÂÄ ã! *
resolution ° d ONLN d\4 <@• (\ ZPand Copybits to copy the pattern into the object that needs to be filled, using ° d ONLN d¨4•@˛ (\√the “cookie cutter” ° d ONLN d¿@ <L ∑ (h Z approach to fill the object. ° d ONLN d›X <d ] *X-Ref: ° d ONLN d‰d <p ˆ * %Inside Macintosh Volume I, page I-150
(C Z+If there is not enough stack space for one ° d ONLN dè
'˛ )Œ1row of the image, then CopyBits tries to allocate ° d ONLN d¡' <3 ö (O Ztemporary memory. ° d ONLN d”? <KO *4Before allocating temporary memory, CopyBits checks ° d ONLN d ?OK˛ (gm!if the temporary memory traps are ° d ONLN d )K <W- (s Z3available. (They are available under both System 6 ° d ONLN d \K-W˛ )Ò+MultiFinder and System 7.) If the traps are ° d ONLN d àW <c ( ZDavailable, CopyBits tries to allocate a 256K byte buffer for use as ° d ONLN d ÃWc˛ (ùa “fake” stack. (CopyBits ° d ONLN d Êc <o V (ã Zused ° d ONLN d Îc Vo˛ )Tto try for a 64K block, but this has been changed, and it may change again.) If this ° d ONLN d
@o <{) (ó Z4succeeds, then all is well and the image is copied. ° d ONLN d
to){˛ )Ì+If the temporary memory traps do not exist, ° d ONLN d
†{ <ár (£ Z=or if CopyBits cannot allocate a 256K buffer, then the image ° d ONLN d
›{rᲠ(£êis not copied and CopyBits ° d ONLN d
¯á <ì a (Ø Zreturns. ◊ X◊
*=Basic QuickDraw Q&As (Ï˙13 )
of 22 ˇÆ ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘
° d ONLN d ) ï *CopyBits does not check ° d ONLN d ï )⁄ )}Bin the application heap for free memory, at least not for its work ° d ONLN d [ ) 5 a ( Q 6buffer. For its ° d ONLN d k ) a 5⁄ )INwork buffer it will only use the stack, and after that it resorts to temporary ° d ONLN d ∫ 5 A û ( ] 6 memory, if available. There ° d ONLN d ÷ 5 û A⁄ )Ü?are some circumstances that may cause memory allocations in the ° d ONLN d A M{ ( i 6Japplication heap, but this memory is not used for CopyBits’s image buffer. ° d ONLN da Y eÑ *NAlso, please note that the implementation of CopyBits is subject to change in ° d ONLN dØ YÑ e⁄ ( Å¢future versions of ° d ONLN d¬ e q R ( ç 6
QuickDraw.
° d ONLN dÕ â òã *'2PICTs with PostScript PICT comments and memory use
° d ONLN d ò § > * Written: ° d ONLN d ò d § à )L1/10/92 ° d ONLN d § ∞ ] ( à 6Last reviewed: ° d ONLN d § d ∞ à )L2/17/92 ° d ONLN d( º » K ( ‰ 6 Why does ° d ONLN d1 º K »⁄ )3Jmy PICT (including dotted lines) use so much memory when drawn in MacDraw, ° d ONLN d| » ‘ø ( 6Sand even more when drawn in SuperPaint? Do they include PicComments for PostScript? ° d ONLN d– ‘ ‡ * * ___ ° d ONLN d‘ Ï ¯¶ *OYour guess that it has to do with PicComments is quite right; both MacDraw and ° d ONLN d# ϶ ¯⁄ (ƒ
@`L⁄ (h~sequence of “ShortLine” ° d ONLN d%L X õ (t 6opcodes. So, another piece ° d ONLN d@L õX⁄ )ÉBof explanation for the large PICT size basically is that QuickDraw ° d ONLN dÉX dW (Ä 6Edoes not have facilities to describe dotted lines in an economic way. ° d ONLN d…p |∂ *YSuperPaint also includes a copy of a proprietary dictionary, which adds substantially to ° d ONLN d"p∂|⁄ (ò‘the size ° d ONLN d+| ày (§ 6Gof a PICT. On the other hand, the code that resides in that dictionary ° d ONLN dr|yà⁄ (§ómakes the picture’s ° d ONLN dÜà î (∞ 68PostScript representation that much better. Ultimately, ° d ONLN dæàî⁄ (∞9"WYSIWYG is the goal, and sometimes ° d ONLN d·î †z (º 6Pit takes a little extra code to make that happen. (Incidentally, the PostScript ° d ONLN d1îz†⁄ (ºòdictionary contained ° d ONLN dF† ¨r (» 6Fin pictures created by older versions of SuperPaint makes assumptions ° d ONLN då†r¨⁄ (»êabout the contents of ° d ONLN d¢¨ ∏ (‘ 6.the LaserPrep file which are not true for the ° d ONLN d–¨∏⁄ )Î*recent versions of the LaserWriter driver. ° d ONLN d˚∏ ƒe (‡ 6FDocuments containing such pictures will not print correctly any more.) ° d ONLN dB– ‹a *DTo determine the primitives that define other nonstandard QuickDraw ° d ONLN dÜ–a‹⁄ (¯objects found in drawing ° d ONLN dü‹ Ë# ( 62applications, you can use MPW’s DeRez function or ° d ONLN d—‹#Ë⁄ (A%a third-party utility such as Palomar ° d ONLN d˜Ë Ù
( 60Software’s PICT Detective on the resource PICT. ° d ONLN d 'Ë
Ù⁄ )ı)These tools will provide the opcodes that ° d ONLN d QÙ g ( 6define the PICT.
° d ONLN d b 'û *'8Inside Macintosh Vol. V PICT opcode size should be fixed
° d ONLN d õ' 3 > * Written: ° d ONLN d §' d3 à )L1/22/92 ° d ONLN d ¨3 ? ] ([ 6Last reviewed: ° d ONLN d ª3 d? à )L2/28/92 ° d ONLN d √K Wi (s 6EThe definition of PICT version 2 on pages 92-105 of Inside Macintosh ° d ONLN d
KiW⁄ (sáVolume V says that the ° d ONLN d
W c ¬ ( 6#data size of the opcodes $001A and ° d ONLN d
BW ¬c⁄ )™9$001B is variable, but also that the data is an RGBColor. ° d ONLN d
|c o
(ã 61This is confusing, since the size of an RGBColor ° d ONLN d
≠c
o⁄ )ı(is fixed at six bytes. How can these two ° d ONLN d
÷o { ı (ó 6.opcodes vary in the amount of associated data? ° d ONLN d { á * * ___ ° d ONLN d ì ü¥ *ZSeems like you’ve run into a cut/paste problem. All the opcodes that refer to table 4 are ° d ONLN d cì¥ü⁄ (ª“new for ° d ONLN d kü ´( (« 64Color QuickDraw. Also, most of them are variable in ° d ONLN d üü(´⁄ («F"length, so the author simply had a ◊ 4◊˘
(Ï 614 )
of 22 (ÏñBasic QuickDraw Q&As ˇp ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +Z-Developer Support Center ( -Ê October 1992 / X /
° d ONLN d < ) ( E Z(standard notation for anything that was ° d ONLN d ( )˛ )Õ.explained further in table 4 (page V-103). The ° d ONLN d W ) < 5 œ ( Q Z information contained in table ° d ONLN d v ) œ 5˛ )ì?4 is, in fact, accurate. The size information of several of the ° d ONLN d ∂ 5 < A¿ ( ] ZRopcodes listed is not variable even though the preceding pages told you they were. ° d ONLN d M < Y> *9All you gotta do is believe table 4 and you will be fine.
° d ONLN dC q < Äã *'1Code for filling an area fully bounded by polygon
° d ONLN du Ä < å b * Written: ° d ONLN d~ Ä à å ¨ )L2/21/92 ° d ONLN dÜ å < ò Å ( ¥ ZLast reviewed: ° d ONLN dï å à ò ¨ )L6/11/92 ° d ONLN dù § < ∞ ( à Z]Currently, when a polygon is filled, an even-odd rule is applied to determine which areas of ° d ONLN d˙ § ∞˛ ( Ãthe ° d ONLN d˛ ∞ < ºâ ( ÿ ZHpolygon are to be filled. For our application, we also need to fill all ° d ONLN dF ∞â º˛ ( ÿßthe areas of the defined ° d ONLN d_ º < »O ( ‰ Z;polygon. Is there a relatively easy way to accomplish this? ° d ONLN dõ » < ‘ N * ___ ° d ONLN dü ‡ < Ï ≥ *There are many different ° d ONLN d∏ ‡ ≥ Ï˛ )wAways to fill polygons, as you may know. If you do not want to use ° d ONLN d˙ Ï < ¯2 ( Z3QuickDraw’s standard FillPoly routine, you’ll have ° d ONLN d- Ï2 ¯˛ )ˆ(to create your own. The following sample ° d ONLN dV ¯ <Û ( Zaillustrates one technique that might be used to fill the area fully bounded by a polygon. It can ° d ONLN d∑ ¯Û˛ ( be ° d ONLN d∫ <ù (, ZKdropped right into the traffic light sample (sample.p) that ships with MPW ° d ONLN dù˛ (,ªas a replacement for ° d ONLN d < ø (8 ZOits DrawWindow procedure. The green star is drawn using FillPoly and the black ° d ONLN diø ˛ (8›
star is drawn ° d ONLN dw <(d (D Z=using my filling technique that uses an offscreen bitmap and ° d ONLN d¥ d(˛ (DÇ calcMask to fill in the poly the ° d ONLN d’( <4 ì (P Zdesired way, then ° d ONLN dÁ( ì4˛ )WJCopyBits to transfer it to the onscreen port. The drawbacks of this method ° d ONLN d24 <@W (\ ZBare that it is not as fast as writing a specialized poly routine; ° d ONLN dt4W@˛ (\u&the benefits are that it’s small, fast ° d ONLN dõ@ <Lö (h ZHenough for most operations, and can be used for more than just polygons. ,
Courier
° d ONLN d‰X <c i * {$S Main} ° d ONLN dÓb <m *
(PROCEDURE DrawWindow(window: WindowPtr); ° d ONLN dv <Å Õ * var MyPoly:PolyHandle; ° d ONLN d5Ä <ã π *
& If MemError <>noErr THEN BEGIN ° d ONLN dÏ ≥ æ Æ *
SetPort(SavePort); ° d ONLN d Ω » ≥ *
ClosePort(newPort); ° d ONLN d+ « “ Ã *
$ DisposPtr(ptr(newPort)); ° d ONLN dP — ‹ Ω *
! CreateOffport:=false; ° d ONLN dr € Ê Y *
END ° d ONLN dÄ Â w *
ELSE BEGIN ° d ONLN dî Ô ˙ ∏ *
EraseRect(inBounds); ° d ONLN dµ ˘ « *
# newOffscreen :=newPort; ° d ONLN dŸ Æ *
setPort(SavePort); ° d ONLN d¯
∏ *
CreateOffPort:=true; ° d ONLN d " T *
end; ° d ONLN d&! , @ *
end; ° d ONLN d35 @ *4 Procedure KillOffPort(oldOffscreen :GrafPtr); ° d ONLN dh? J E *
Begin ° d ONLN drI T ∏ *
ClosePort(oldOffscreen); ° d ONLN dìS ^ *
3 DisposPtr(OldOffscreen^.portBits.baseAddr); ° d ONLN d«] h — *
% DisposPtr(ptr(OldOffScreen)); ° d ONLN dÌg r @ *
End; ° d ONLN dˆ{ Ü 1 *BEGIN ° d ONLN d¸Ö êè *
K If NOT (CreateOffPort(offPort,window^.portRect)) THEN Exit(DrawWindow); ° d ONLN dHè öä *
J If NOT (CreateOffPort(onPort,window^.portRect)) THEN Exit(DrawWindow); ° d ONLN dó£ Æ | * SetPort(window); ° d ONLN d¨∑ ¬ r * MyRgn:=NewRgn; ° d ONLN dø¡ à T *
OpenRgn; ° d ONLN dÃÀ ÷ Ü *
MoveTo(10,25); ° d ONLN d„’ ‡ Ü *
Lineto(70,25); ° d ONLN d˙fl Í Ü *
Lineto(15,70); ° d ONLN dÈ Ù Ü *
Lineto(40,10); ° d ONLN d(Û ˛ Ü *
Lineto(65,70); ° d ONLN d?˝ Ü *
Lineto(10,25); ° d ONLN dV | *
CloseRgn(MyRgn); ° d ONLN dk & Å * MyPoly:=OpenPoly; ° d ONLN dÅ% 0 Ü *
° d ONLN dKW <f« *&7Use crsrNew flag to unobscure cursor without mouse move
° d ONLN dÉf <r b * Written: ° d ONLN dåf àr ¶ )L3/3/92 ° d ONLN dìr <~ Å (ö ZLast reviewed: ° d ONLN d¢r à~ ¨ )L6/11/92 ° d ONLN d™ä <ñU (≤ Z4The Macintosh QuickDraw routine ObscureCursor hides ° d ONLN dfiäUñ˛ (≤s"the cursor until the next time the ° d ONLN dñ <¢Ó (æ ZXmouse is moved but isn’t affected by HideCursor or ShowCursor. Our application needs to ° d ONLN dYñÓ¢˛ (æ use ° d ONLN d]¢ <ÆÓ ( ZZObscureCursor while the user is typing but needs the cursor to be visible after no typing ° d ONLN d∑¢ÓÆ˛ ( has ° d ONLN dªÆ <∫ (÷ Z'occurred for a short period. How do we ° d ONLN d‚Æ∫˛ )»0“undo” ObscureCursor, since we can’t rely on the ° d ONLN d∫ <Δ Ø (‚ Zuser moving the mouse? ° d ONLN d*Δ <“ N * ___ ° d ONLN d.fi <Í ˘ *%The only way to unobscure the cursor ° d ONLN dSfi ˘Í˛ )Ω2is to convince the system that the mouse has moved ° d ONLN dÜÍ <ˆ/ ( Z5again. There is no real good way to do this via tool ° d ONLN dªÍ/ˆ˛ )Û,calls, so you are going to have to do it the ° d ONLN dˈ < T ( Zhard ° d ONLN d̈ T˛ )Uway and simply update the low-memory cursor information to tell the system the cursor ° d ONLN dC <z (* ZBmoved (even though you do not need to update the actual position). ° d ONLN dÜ <&Œ *OTo tell the system the cursor has changed location, you simply set the crsrNew ° d ONLN d’Œ&˛ (BÏ
flag to 1; ° d ONLN d‡& <2_ (N Z9crsrNew is a byte located at $08CE. When the system sees ° d ONLN d&_2˛ (N}!this byte is 1 it will assume the ° d ONLN d;2 <>è (Z ZGcursor has moved, unobscure it, redraw at the appropriate place (where ° d ONLN dÇ2è>˛ (Z≠it was all along...) and ° d ONLN dõ> <J˛ (f Z]reset crsrNew waiting for the mouse to move again, as in the following C and Pascal examples:
° d ONLN d˘V <a ™ */* the C version... */ ° d ONLN d` <k Õ *
void UnObscureCursor ( void ) ° d ONLN d.j <u A *
{ ° d ONLN d0t < ™ *
*(char *)0x8CE = 1; ° d ONLN dG~ <â A *
} ◊ X◊
*GBasic QuickDraw Q&As (Ï˙17 )
of 22 ˇ
î ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘ ,
Courier
° d ONLN d ' 2 ê *!(* the pascal version *) ° d ONLN d 1 < ö *
Procedure UnObscureCursor; ° d ONLN d 4 E P 1 *begin ° d ONLN d : O Z r *
ptr($08CE)^:=1; ° d ONLN d M Y d , *
end;
° d ONLN d R o {3 *;This will do what you want in a short, easy-to-use package.
° d ONLN d é ì ¢
*'!Macintosh QuickDraw region quirks
° d ONLN d ∞ ¢ Æ > * Written: ° d ONLN d π ¢ d Æ Ç )L1/1/90 ° d ONLN d ¿ Æ ∫ ] ( ÷ 6Last reviewed: ° d ONLN d œ Æ d ∫ é )L11/21/90 ° d ONLN d ÿ Δ “ , ( Ó 6I’m ° d ONLN d ‹ Δ , “⁄ )Sworking with regions, and I’m having problems with Macintosh QuickDraw trashing the ° d ONLN d0 “ fi1 ( ˙ 68heap and crashing, even though my regions are under 32K. ° d ONLN di fi Í * * ___ ° d ONLN dm ˆ ï *There are some quirks in ° d ONLN dÜ ˆ ï÷ )}<the current version of QuickDraw. Here are some the commonly ° d ONLN d¬ ˆ÷⁄ ( Ù- ° d ONLN d√ É (* 6encountered problems: ° d ONLN dŸ & ö *1. When doing operations ° d ONLN dÚ ö&⁄ )Ç;which use more than one region, sduch as UnionRgn, DiffRgn, ° d ONLN d.& 28 (N 67XorRgn, or SectRgn, the sum of the sizes of the source ° d ONLN de&82a (NVregions ° d ONLN dm&a2ª ))must be less than ° d ONLN d~&ª2⁄ )Z 32K, ° d ONLN dÑ2 > Í (Z 6/regardless of the size of the resulting region. ° d ONLN d¥J VO *D2. FrameRgn will fail if it tries to frame a region bigger than 16K. ° d ONLN d˘b n ¥ *#3. If CloseRgn fails, the internal ° d ONLN d b ¥n⁄ )ú>region data is already corrupt; there is nothing you can do to ° d ONLN d[n zπ (ñ 6]recover. CloseRgn will also fail if there isn’t at least a 32K block of free space available. ° d ONLN dπÜ í ° *Here are some workarounds: ° d ONLN d‘û ™ É *1. Keep regions small ° d ONLN dÍû É™⁄ )kFand not too complex. Keep track of the sizes of all regions so you can ° d ONLN d1™ ∂k (“ 6Icheck the SUM of the sizes before calling a routine that has a 32K limit. ° d ONLN d{¬ Œ¨ *V2. Keep 32K free, or allocate a 32K block and release it just before calling CloseRgn. ° d ONLN d“⁄ Ê” *[Apple is working on these problems and expects to fix them in future versions of QuickDraw.
° d ONLN d.˛
V *',How to get Macintosh QuickDraw arc endpoints
° d ONLN d[
> * Written: ° d ONLN dd
d Ç )L1/1/90 ° d ONLN dk % ] (A 6Last reviewed: ° d ONLN dz d% é )L11/21/90 ° d ONLN dÉ1 = Í (Y 6*Is there a way to obtain the endpoints of ° d ONLN d≠1 Í=⁄ )“+an arc drawn by the Macintosh QuickDraw arc ° d ONLN dŸ= I fl (e 6(routines, such as FrameArc and PaintArc? ° d ONLN dI U * * ___ ° d ONLN da mó *OGiven a rectangle R which frames the arc you wish to draw, convert your angles ° d ONLN dUaóm⁄ (âµto an absolute ° d ONLN ddm yö (ï 6Qcoordinate system, where three o’clock is 0 degrees and 12 o’clock is 90 degrees. ° d ONLN d∂Ö ë E * Now, let:
° d ONLN d¿ù ® ÷ *& x = .5 (+ or -) (R.right - R.left) ◊ 4◊˘
*(18 )
of 22 (ÏñBasic QuickDraw Q&As ˇ
d ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +Z-Developer Support Center ( -Ê October 1992 / X / ,
Courier
° d ONLN d < ( ˙ ( D Z& y = .5 (+ or -) (R.bottom - R.top)
° d ONLN d ' 3 < ? *-The endpoint of the curve will be defined by:
° d ONLN d U K < V ı *% EndPoint.h = x (+ or -) cos(ang); ° d ONLN d { U < ` ı *
% EndPoint.v = y (+ or -) sin(ang);
° d ONLN d ° k < w ˝ *+h & v are relative to center of rectangle R ° d ONLN d Õ É < è ’ * This calculates only the upper ° d ONLN d Ï É ’ è˛ )ô;endpoint of the arc, but you can easily calculate the other ° d ONLN d( è < õ „ ( ∑ Z endpoint using the same formula ° d ONLN dH è „ õ˛ )ß9by calculating the absolute angle for the start point and ° d ONLN dÇ õ < ß Ω ( √ Zapplying the same formula. ° d ONLN dù ≥ < øô *KHere is a subroutine which illustrates the algorithm, in LightSpeed Pascal:
° d ONLN dÈ À < ÷Å *A{ DrawCurve: draw an arc from 0 degrees until the point defined } ° d ONLN d+ ’ < ‡J *
6{ by 'angle'. At that point draw a 4 by 4 crosshair. } ° d ONLN dz È < Ù@ *4procedure DrawCurve (frame : Rect; angle : integer); ° d ONLN dØ ˝ < K *var ° d ONLN d≥ < ë *
x, y : integer; ° d ONLN d≈ < † *
xr, yr : extended; ° d ONLN d⁄ <& ë *
rad : extended; ° d ONLN dÏ/ <: U *begin ° d ONLN dÚC <N “ * { Convert angle to radians } ° d ONLN dM <X ˙ *
& rad := (90 - angle) / 180 * 3.14159; ° d ONLN d8a <l † * { Find end point } ° d ONLN dMk <v6 *
2 yr := (frame.bottom - frame.top) * sin(rad) / 2; ° d ONLN d≥ <äT *
8 x := (frame.right + frame.left) / 2 + Num2Integer(xr); ° d ONLN dÏâ <îT *
8 y := (frame.bottom + frame.top) / 2 + Num2Integer(yr); ° d ONLN d%ù <® † * { Draw crosshair } ° d ONLN d:ß <≤ õ *
MoveTo(x - 4, y); ° d ONLN dN± <º õ *
LineTo(x + 4, y); ° d ONLN dbª <Δ õ *
MoveTo(x, y - 4); ° d ONLN dv≈ <– õ *
LineTo(x, y + 4); ° d ONLN däŸ <‰ Ç * { Draw arc } ° d ONLN dô„ <Ó » *
FrameArc(frame, 0, angle); ° d ONLN d∂Ì <¯ P *
end;
° d ONLN dª < c *&*Macintosh CopyBits no longer limited to 3K
° d ONLN dÊ <* b * Written: ° d ONLN dÔ à* ¶ )L5/3/89 ° d ONLN dˆ* <6 Å (R ZLast reviewed: ° d ONLN d* à6 ≤ )L11/21/90 ° d ONLN dB <NÙ (j Z_Inside Macintosh Volume I (page 188) says there is a 3K limit for CopyBits. Is this still true? ° d ONLN dnN <Z N * ___ ° d ONLN drf <rÜ *HThe CopyBits limit is obsolete; there is no longer a 3K limit. The limit ° d ONLN dªr <~Ü * Bdepends on the amount of RAM in your Macintosh. CopyBits tries to ° d ONLN d˝rÜ~˛ (ö§use the stack to do all of ° d ONLN d~ <äé (¶ ZHthe copying. In most cases CopyBits is able to copy entire screen shots ° d ONLN d`~éä˛ (¶¨at one time. You might ° d ONLN dwä <ñ ° (≤ Zrun into problems if ° d ONLN dåä °ñ˛ )eByou don’t have enough stack to hold two times the rowBytes of your ° d ONLN dœñ <¢≥ (æ ZPsource, but even in this case CopyBits will attempt to find the memory it needs. ◊ X◊
*.Basic QuickDraw Q&As (Ï˙19 )
of 22 ˇ ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘
° d ONLN d ) 5 9 *$X-Ref: ° d ONLN d 5 A * #Inside Macintosh Volume I, page 188
° d ONLN d + Y hº *';Why grafPort’s clipRgn should be changed before OpenPicture
° d ONLN d g h t > * Written: ° d ONLN d p h d t à )L11/1/90 ° d ONLN d x t Ä ] ( ú 6Last reviewed: ° d ONLN d á t d Ä é )L12/19/90 ° d ONLN d ê å ò + ( ¥ 6On ° d ONLN d ì å + ò⁄ )Qpage 189 of Inside Macintosh, Volume I, in the QuickDraw chapter’s description of ° d ONLN d  ò § – ( ¿ 6&OpenPicture, is the following warning: ° d ONLN d ∞ ºÇ *P“A grafPort's clipRgn is initialized to an arbitrarily large region. You should ° d ONLN d\ ∞Ç º⁄ ( ÿ†always change the ° d ONLN dn º » ( ‰ 6YclipRgn to a smaller region before calling OpenPicture, or no drawing may occur when you ° d ONLN d« º »⁄ ( ‰Ëcall ° d ONLN dà » ‘ \ ( 6
DrawPicture.” ° d ONLN d⁄ ‡ Ï — *(The “arbitrarily large” clipping region ° d ONLN d ‡ — Ï⁄ )π4rectangle is set to -32767,- 32767,32767,32767 (top, ° d ONLN d7 Ï ¯ “ ( 6)left, bottom, right) for new ports. This ° d ONLN d` Ï “ ¯⁄ )∫;is the largest rectangle possible. If this is not a "valid" ° d ONLN dú ¯ n ( 6clipping rectangle ° d ONLN dØ ¯ n⁄ )VOfor pictures, what is? Is there some specific limit to the size of the clipping ° d ONLN dˇ ã (, 6Prectangle? Does it depend on either available memory or the size of the picture? ° d ONLN dP * * ___ ° d ONLN dT( 4¥ *ZInside Macintosh ’s warning is based on truth but it’s incomplete. It didn’t actually say ° d ONLN dÆ(¥4⁄ (P“ that this ° d ONLN d∏4 @= (\ 6Crectangle is invalid as a clipping region, because this is in fact ° d ONLN d˚4=@⁄ (\["a perfectly valid clipping region. ° d ONLN d @ Là (h 6FBut, you could run into problems if you use this as a clipping region ° d ONLN dd@àL⁄ (h¶when creating a ° d ONLN dtL X ˛ (t 62QuickDraw picture. It’s not a matter of available ° d ONLN d¶L ˛X⁄ )Ê.memory or size; it’s a simple matter of 16-bit ° d ONLN d’X d ‘ (Ä 6&signed integer overflow and underflow. ° d ONLN d¸p | 9 *When ° d ONLN dp 9|⁄ )!Syou open a picture, the current clip region is recorded in the picture (this wasn’t ° d ONLN dU| ày (§ 6Enecessarily true in some early versions of QuickDraw). When you draw ° d ONLN dö|yà⁄ (§óthe resulting picture ° d ONLN d∞à î r (∞ 6using the picture’s ° d ONLN dƒà rî⁄ )ZJpicFrame as the destination rectangle, there won’t be any problems. But if ° d ONLN dî †A (º 6Ayou use a destination rectangle that’s larger than the picFrame, ° d ONLN dPîA†⁄ (º_ QuickDraw scales everything in ° d ONLN do† ¨ L (» 6 the picture ° d ONLN d{† L¨⁄ )4Uproportionately, including the clip region. If you allowed the default clip region to ° d ONLN d—¨ ∏ (‘ 68be recorded into the picture, then its rgnBBox, already ° d ONLN d ¨ ∏⁄ (‘:'as large as possible, will be made even ° d ONLN d1∏ ƒA (‡ 6:larger. That means that the -32767 coordinates might wrap ° d ONLN dk∏Aƒ⁄ (‡_ around to the positive number ° d ONLN d⃠–§ (Ï 6Qrange, and the 32767 coordinates might wrap around to the negative number range. ° d ONLN d⁄ƒ§–⁄ (Ϭ This leaves ° d ONLN dÊ– ‹& (¯ 69you with an empty clip region. Nothing at all gets drawn ° d ONLN d –&‹⁄ (¯D&when the current port’s clip region is ° d ONLN dF‹ Ë 9 ( 6empty. ° d ONLN dMÙ Ÿ *(If the destination rectangle is smaller ° d ONLN duÙ Ÿ ⁄ )¡/than the picture’s picFrame, you won’t have any ° d ONLN d• ´ (( 6Uproblems because the default clip region will be made smaller, and that’s no problem. ° d ONLN d˚ $∫ *UThis is why Inside Macintosh suggests that you make the clip region smaller than the ° d ONLN d P∫$⁄ (@ÿdefault ° d ONLN d X$ 0µ (L 6Sclip region before opening a picture. By doing this, you’re almost guaranteed that ° d ONLN d ´$µ0⁄ (L”the clip ° d ONLN d ¥0 < ¨ (X 6 region won’t get scaled to the ° d ONLN d ”0 ¨<⁄ )î=point that it turns inside out. What size should you make it? ° d ONLN d
< H§ (d 6SSmall enough so that the risk of the clip region’s coordinates being scaled out of ° d ONLN d
d<§H⁄ (d¬ QuickDraw ° d ONLN d
nH Tê (p 6Scoordinate space is minimal. I usually just set the clip region to the picFrame of ° d ONLN d
¡HêT⁄ (pÆthe picture. It’s ° d ONLN d
”T ` ô (| 6hard to go wrong this way. ◊ 4◊˘
*p20 )
of 22 (ÏñBasic QuickDraw Q&As ˇÚ ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +Z-Developer Support Center ( -Ê October 1992 / X /
° d ONLN d ) < 8} ( T Z+Macintosh CalcMask and CopyMask code sample
° d ONLN d , 8 < D b * Written: ° d ONLN d 5 8 à D ¨ )L2/27/92 ° d ONLN d = D < P Å ( l ZLast reviewed: ° d ONLN d L D à P ¨ )L5/21/92 ° d ONLN d T \ < h Ù ( Ñ Z(I can’t get the black-and-white version ° d ONLN d | \ Ù h˛ )∏5of my lasso-type tool to work correctly with CalcMask ° d ONLN d ≤ h < tŸ ( ê ZPand CopyMask. With CalcCMask it seems to work fine. What could I be doing wrong? ° d ONLN d t < Ä N * ___ ° d ONLN d å < òs *>CalcMask and CalcCMask are similar in that they both generate ° d ONLN dE ås ò˛ ( ¥ëa 1-bit mask given a source ° d ONLN da ò < §, ( ¿ Z-bitmap. With CalcCMask, though, a pixMap can ° d ONLN dé ò, §˛ )*be used in place of the source bitmap; the ° d ONLN dπ § < ∞ ( à Z(seedRGB determines which color sets the ° d ONLN d· § ∞˛ )»2bits in the mask image. An easy mistake to make is ° d ONLN d ∞ < º= ( ÿ Z7to forget that CalcCMask accepts a pointer to a bitmap ° d ONLN dK ∞= º˛ ( ÿ['data structure while CalcMask expects a ° d ONLN ds º < » ü ( ‰ Zpointer to the actual ° d ONLN dâ º ü »˛ )cBbit image. And unlike CalcCMask, which uses bounding Rects for the ° d ONLN dà » < ‘ı ( ZPimage’s dimensions, CalcMask uses the bitmap’s rowBytes and pixel image offsets ° d ONLN d »ı ‘˛ ( to ° d ONLN d ‘ < ‡Ã ( ¸ ZUdetermine the bounding Rects for the image. A typical call to these routines would be ,
Courier
° d ONLN du Ï < ˜ ¥ * BitMap source, mask; ° d ONLN dé ˆ <r *
> CalcMask (source.baseAddr, mask.baseAddr, source.rowBytes, ° d ONLN dŒ < ê *
D mask.rowBytes, source.bounds.bottom-source.bounds.top, ° d ONLN d
< Ê *
" source.rowBytes>>1); ° d ONLN d7 < Ü *
B CalcCMask (&source, &mask, &(*source).bounds, &(*mask).bounds, ° d ONLN d{ <) · *
! &seedRGB, nil, 0);
° d ONLN dù4 <@. *3One last thing to note when using CalcMask is that ° d ONLN d–4.@˛ )Ú*the width of the image is in words and not ° d ONLN d˚@ <L: (h Z4bytes. To learn more about these routines, see page ° d ONLN d/@:L˛ )˛$24 of Inside Macintosh Volume IV and ° d ONLN dTL <X– (t ZRpage 72 of Inside Macintosh Volume V. Also, the Developer CD Series disc contains ° d ONLN d¶L–X˛ (tÓ a sample, ° d ONLN d∞X <d| (Ä Z>CalcCMask&CalcMask, that shows how to use both these routines.
° d ONLN dÔ| <ãí *'-Macintosh QuickDraw LineTo bug and workaround
° d ONLN d ã <ó b * Written: ° d ONLN d&ã àó ¨ )L4/23/92 ° d ONLN d.ó <£ Å (ø ZLast reviewed: ° d ONLN d=ó ࣠¨ )L7/13/92 ° d ONLN dEØ <ª2 (◊ Z1Our zooming function crashes into flames when we ° d ONLN dvØ2ª˛ )ˆ*pass valid coordinate values to LineTo, as ° d ONLN d°ª <« ¥ („ Zin the following example:
° d ONLN dª” <fi † * SetPort(myPort); ° d ONLN d–› <Ë ™ *
ç <ô Á (µ Z×, splitting the operation in two. ◊ X◊
*7Basic QuickDraw Q&As (Ï˙21 )
of 22 ˇ ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘
° d ONLN d ) û * Replacing the bottlenecks is ° d ONLN d û )⁄ )Ü@a very straightforward operation (which you are probably already ° d ONLN d ^ ) 5 ≠ ( Q 6 using) and in most of the cases ° d ONLN d ~ ) ≠ 5⁄ )ïAwill only result in another level of indirection into StdLine but ° d ONLN d ¿ 5 A ´ ( ] 6 that will prevent your program ° d ONLN d fl 5 ´ A⁄ )ì=from calling QuickDraw with parameters that are guaranteed to ° d ONLN d A M \ ( i 6cause crashes.
° d ONLN d, e t *' QuickDraw globals at INIT time " Ñ 3
° d ONLN dK t Ä > * Written: ° d ONLN dT t d Ä Ç )L6/1/92 " ì 3 ° d ONLN d[ Ä å ] ( ® 6Last reviewed: ° d ONLN dj Ä d å à )L9/15/92 " ü 3 " ´ 3 ° d ONLN dr ò §? ( ¿ 6@If I call InitGraf before I reference CurrentA5, will CurrentA5 ° d ONLN d≤ ò? §⁄ ( ¿] be valid and can the QuickDraw " ∑ 3 ° d ONLN d— § ∞7 ( à 6;globals be referenced off it? The screenBits bounds values ° d ONLN d §7 ∞⁄ ( ÃU seem screwy on some machines. " √ 3 ° d ONLN d* ∞ ºS ( ÿ 6@Does the problem lie with CurrentA5? Should I be referencing A5? " œ 3 ° d ONLN dk º » * * ___ " € 3 " Á 3 ° d ONLN do ‘ ‡ ÷ *%Here’s the process used by ShowINIT, ° d ONLN dî ‘ ÷ ‡⁄ )æ3which is remarkably compatible with system software " Û 3 ° d ONLN d» ‡ ÏQ ( 6<and other INITs (and it had better be, because it’s used by ° d ONLN d ‡Q Ï⁄ (omore than half the system " ˇ 3 ° d ONLN d Ï ¯ } ( 6extensions available): " 3 " 3 ° d ONLN d5 ; *B1. It saves the value in the CurrentA5 global to restore it later. "# 3 ° d ONLN dx b * I2. It points the A5 register at 4 bytes of storage for use by the system. "/ 3 ° d ONLN d¬ (. * ;3. It copies the value now in A5 into the CurrentA5 global. "; 3 ° d ONLN d˛( 4¡ * ^4. It calls InitGraf, passing a pointer to the thePort field of a QuickDraw globals structure. "G 3 ° d ONLN d]4 @§ * V5. It opens a port and draws as necessary. [This is where all the functionality goes.] "S 3 ° d ONLN d¥@ L æ * '6. After it’s done, it closes its port. "_ 3 ° d ONLN d‹L X, * >7. It copies the value saved in step (1) into the A5 register. "k 3 ° d ONLN dX d3 * =8. It copies the restored A5 value into the CurrentA5 global. "w 3 "É 3 ° d ONLN dYp | d *To summarize, ° d ONLN dgp d|⁄ )LIShowINIT saves the A5, creates and initializes its own A5 world, does its "è 3 ° d ONLN d±| àé (§ 6Kdrawing, then restores the previous A5 world. For more information on this ° d ONLN d¸|éà⁄ (§¨subject, see the "õ 3 ° d ONLN d
à î ˚ (∞ 6,Macintosh Technical Note “Stand-Alone Code.” "ß 3 ◊ 4◊˘
(Ï 622 )
of 22 (ÏñBasic QuickDraw Q&As ˇ ◊# ˇ ˇˇˇˇ # ◊ † Ç
/ Z Å#
0Ià:µú9 " { ˇˇˇˇˇˇˇˇ # † ƒ ° d
ONLN f ˛ † å ° d 1drw2 … -·_ Ä ˇˇˇˇˇˇ è ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˙ ó@ † ò , Times
. R… R… +]BNew Technical Notes † ô ° d drw2 : °„ † ó ° d 1drw2 eÙ Ä ˇˇˇˇˇˇ P ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä E¿ † ò
( {ïDeveloper Support † ô ° d drw2 : °„ † ó ° d `drw2 - Ô ˇˇˇˇˇˇ K Ô - Z f f Z ° d 1drw2 ¿˙È ˇˇˇˇˇˇ K ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : 0 ° ö ˇÙ Ä † ò
0 ( UÔ † ô ° d drw2 : °„ † ó ° d 1drw2 ÔÊ˙ ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˝Ä † ò
+& ® † ô ° d drw2 : °„ † ó ° d 1drw2  -¯ y ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä % † ò
( Z \ Macintosh † ô ° d drw2 : °„ † ó † ç ° d drw2 D † É
IR . ° d ONLN d z < çS ( ß Z So Many Bitmaps, So Little Time
° d ONLN d å < õ r *Imaging ° d ONLN d ( åg õ˛ ( ∑ÖM.IM.BitMatToRegion
° d ONLN d < ß < ≥ t ( œ Z Revised by: ° d ONLN d H ß Ñ ≥ ¿ )H Rich Collyer ° d ONLN d U ߥ ≥˛ ( œ“
December 1989 ° d ONLN d c ≥ < ø q ( € Z Written by: ° d ONLN d o ≥ Ñ ø ¥ )H
Rick Blair ° d ONLN d z ≥À ø˛ ( €È
April 1988 ° d ONLN d Ö Ã < ÿ T ( Ù ZThis ° d ONLN d ä Ã T ÿ )%Technical Note discusses the routine ,
Courier ° d ONLN d Ø À ◊j )¥BitMapToRegion ° d ONLN d Ω Ãj ÿ˛ )b , which converts a bitmap to a ° d ONLN d ‹ ÿ < ‰Î ( ZXregion, and is available in the 32-Bit QuickDraw INIT and from Apple Software Licensing. ° d ONLN d5 ‰ < Á * Changes since October 1989: ° d ONLN dP ‰ Á ‡ )´2 Added trap definitions for developers using the ° d ONLN dÇ ‰‡ ˛ )˘32-Bit ° d ONLN dâ < ¸í ( ZGQuickDraw version of this routine without the correct MPW include file. ' X' ° d ONLN d— <!á *%GThe following routine is now available to convert a bitmap to a region:
° d ONLN d- <8r *>FUNCTION BitMapToRegion(region:RgnHandle; bMap:BitMap): OSErr;
° d ONLN döq <}ò *JIf you are using the 32-Bit QuickDraw version of this routine without the ° d ONLN d‰qò}˛ (ô∂correct MPW include ° d ONLN d¯} <â` (• Z@file, then you need to include one of the following definitions: ° d ONLN d9ï <° Z *Pascal
° d ONLN d@≠ <∏Å *AFUNCTION BitMapToRegion (region: RgnHandle; bMap: BitMap): OSErr; ° d ONLN dÇ∑ <¬ ™ *
INLINE $A8D7;
° d ONLN dôÕ <Ÿ D *C
° d ONLN dõÂ <Ü *Bpascal OSErr BitMapToRegion (RgnHandle region, const BitMap *bMap) ° d ONLN dfiÔ <˙ ™ *
= 0xA8D7;
° d ONLN dı < k *Assembly
° d ONLN d˛ <( **_BitMapToRegion OPWORD $A8D7
° d ONLN d)4 <@ á *The region will ° d ONLN d94 á@ )K!be built so that all one bits in ° d ONLN dZ3?5 )íbMap ° d ONLN d^45@˛ ) , are inside the region and all zero bits are ° d ONLN dã@ <L x (h Zoutside of it. ° d ONLN döY <e4 *3As with all QuickDraw calls which change a region, ° d ONLN dÕX4dù )¯BitMapToRegion ° d ONLN d‹YùeΔ )i requires ° d ONLN dÂYΔe˛ )) you to pass ° d ONLN dÒf <r (é Z*an existing region (originally created by ° d ONLN de q1 )ƒ_NewRgn ° d ONLN d"f1rÅ )1). If the region ° d ONLN d4fÅr˛ )Pcannot be built due to an ° d ONLN dNr <~ò (ö ZJinsufficient heap space or a size greater than 32K, then the routine will ° d ONLN dòrò~˛ (ö∂return an appropriate ° d ONLN dÆ~ <ä— (¶ ZUerror code and the region will be empty. If the region would have exceeded 32K, the ° d ONLN d~—ä˛ (¶Ô
error will ° d ONLN dã <ó J (≥ Zbe ° d ONLN dä Jñ û ) rgnTooBigErr ° d ONLN d ã ûó √ )T (-500). ◊ X◊
(Ï Z So Many Bitmaps, So Little Time (Ï1 ) of 2 ˇ ° ¿Ù%%DSIDICT:_cv
currentdict /bu known {bu}if
userdict /_cv known not{userdict /_cv 30 dict put}if
_cv begin
/bdf{bind def}bind def
currentscreen/cs exch def/ca exch def/cf exch def
/setcmykcolor where{/setcmykcolor get /cvcmyk exch def}{/cvcmyk{1 sub 4 1 roll 3{3 index add neg dup 0 lt{pop 0}if 3 1 roll}repeat setrgbcolor pop}bdf }ifelse
/ss{//cf //ca //cs setscreen}bdf
/stg{ss setgray}bdf
/strgb{ss setrgbcolor}bdf
/stcmyk{ss cvcmyk}bdf
/min1{dup 0 eq{pop 1}if}bdf
end
currentdict /bn known {bn}if
† ø¥ ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘
° d ONLN d )∞ *SThis function is useful for a number of situations where you have (or can produce) ° d ONLN d S ∞ )⁄ ( EŒa bitmap ° d ONLN d \ * 6 Ä ( R 6representing an area. ° d ONLN d s * Ä 6 ¿ )h You can use ,
Courier ° d ONLN d ) ¿ 5 ˇ )@ _CalcMask ° d ONLN d à * ˇ 6⁄ )?+ to produce such a bitmap. Once you have a ° d ONLN d ¥ 7 C e ( _ 6region, you can ° d ONLN d ƒ 7 e C )M!perform region operations (i.e., ° d ONLN d  6 B: )ù_PtInRgn ° d ONLN d Ì 7: CB )8, ° d ONLN d Ô 6B BÅ ) _UnionRgn ° d ONLN d ¯ 7Å Có )?, or ° d ONLN d ˝ 6ó B÷ ) _InsetRgn ° d ONLN d 7÷ C⁄ )?) ° d ONLN d D P 8 ( l 6or call ° d ONLN d C 8 O å ) _DragGrayRgn ° d ONLN d D å P œ )T, for example. ° d ONLN d+ \ hY ( Ñ 6CThis call is part of the 32-Bit QuickDraw INIT ($A8D7). If you do ° d ONLN dn \Y h÷ ( Ñwnot wish to depend on 32 ° d ONLN dÜ \÷ h⁄ )}- ° d ONLN dá i u ) ( ë 6Bit ° d ONLN dã i ) u ),QuickDraw, then you can obtain a version of ° d ONLN d∑ h tj )flBitMapToRegion ° d ONLN d≈ ij u⁄ )b in MPW object format ° d ONLN d€ u Å™ ( ù 6Pwhich can be linked into an MPW program, by contacting Apple Software Licensing: ° d ONLN d/ ç Ñ ô ˇ +lApple Software Licensing ° d ONLN dK ô Ñ • * Apple Computer, Inc., ° d ONLN dd • Ñ ±" * 20525 Mariani Avenue, M/S 38-I ° d ONLN dÜ ± Ñ Ω Ô * Cupertino, CA, 95014 ° d ONLN dû Ω Ñ … œ * (408) 974-4667 ° d ONLN d∞ … Ñ ’ * AppleLink: SW.LICENSE ° d ONLN d« ‚ Ó (
63If you licensed the older version of this routine, ° d ONLN d˙ · ÌM )ˆ BitMapRgn ° d ONLN d ‚M Ó¨ )?, contact Software ° d ONLN d ‚¨ Ó⁄ )_ Licensing ° d ONLN d Ó ˙ ( 62about receiving an updated version. We recommend ° d ONLN dR Ó ˙⁄ (9&you update your application to use the ° d ONLN dy ˙ ¥ (" 6 new version as soon as possible. ° d ONLN dö Ø * The new version is now named ° d ONLN d∑ Ø )óBitMapToRegion ° d ONLN d≈ Ø )b# to be consistent with the version ° d ONLN dËØ ⁄ )û in 32-Bit ° d ONLN dÚ , “ (H 6#QuickDraw and the MPW interfaces. ° d ONLN d “, )∫
In addition, ° d ONLN d" +r )>BitMapToRegion ° d ONLN d0 r,⁄ )b offers new features. ° d ONLN dG, 8 v (T 6You can now pass ° d ONLN dX, v8⁄ )^Ea one-bit pixelmap which has been coerced to a bitmap. If you pass a ° d ONLN dû9 E ˚ (a 61pixelmap which is too large, then you will get a ° d ONLN dœ8 ˚Dk )„pixmapTooDeepErr ° d ONLN dfl9kEè )p (-148) ° d ONLN dÁ9èE⁄ )$error. You can ° d ONLN d˜F R W (n 6also pass the ° d ONLN dE WQ è )?portBits ° d ONLN d
F èRä )84 of a window, much like you would do with a call to ° d ONLN dAEäQ… )˚ _CopyBits ° d ONLN dJF…RÕ )?. ° d ONLN dL^ j? (Ü 6>There is a potential problem with this routine, since MPW 3.1 ° d ONLN dä^?j⁄ (Ü]!include files contain information ° d ONLN d¨k w ◊ (ì 6%about 32-Bit QuickDraw. If you want ° d ONLN d—j ◊v9 )øBitMapToRegion ° d ONLN dflk9w= )b ° d ONLN d‡k=w⁄ ) to be available on all machines, ° d ONLN dw É ß (ü 6 then you must use the object ° d ONLN d w ßÉ⁄ )è;file from Software Licensing. The problem is that when you ° d ONLN dZÉ èí (´ 6Mcompile your application with MPW 3.1 or later, the 32-Bit QuickDraw version ° d ONLN dßÉíè⁄ (´∞gets preference ° d ONLN d∑è õ ê (∑ 6over the object file. You ° d ONLN d“è êõ ´ )xmust ° d ONLN d÷è ´õ ˇ ) comment out the ° d ONLN dÁè ˇõ⁄ )T/routine in the include files if you want to use ° d ONLN dú ® Å (ƒ 6the object file. If you ° d ONLN d0ú Å® Ì )ionly care about using ° d ONLN dFõ ÌßO )lBitMapToRegion ° d ONLN dTúO®⁄ )b on machines running 32-Bit ° d ONLN dp® ¥ Ë (– 6)QuickDraw, then you need not do anything. ◊ 4◊˘
(Ï 62 ) of 2 (Ïm So Many Bitmaps, So Little Time ˇ¢ ◊# ˇ ˇˇˇˇ # ◊ ° d WORD S † å ° d WORD R… † Ç
/ Z Å#
0Ià:µú9 " { ˇˇˇˇˇˇˇˇ # † ƒ ° d
ONLN f ˛ † å ° d 1drw2 … -·_ Ä ˇˇˇˇˇˇ è ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˙ ó@ † ò , Times
. WIQkWIQk +]BNew Technical Notes † ô ° d drw2 : °„ † ó ° d 1drw2 eÙ Ä ˇˇˇˇˇˇ P ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä E¿ † ò
Ä ( {ïDeveloper Support † ô ° d drw2 : °„ † ó ° d `drw2 - Ô ˇˇˇˇˇˇ K Ô - Z f f Z ° d 1drw2 ¿˙È ˇˇˇˇˇˇ K ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : 0 ° ö ˇÙ Ä † ò
0 ( UÔ † ô ° d drw2 : °„ † ó ° d 1drw2 ÔÊ˙ ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˝Ä † ò
l +& ® † ô ° d drw2 : °„ † ó ° d 1drw2  -¯ y ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä % † ò
BÄ ( Z \ Macintosh † ô ° d drw2 : °„ † ó † ç ° d drw2 D † É ° d WORD † ç
IR . ° d ONLN d { < éó ( ® Z'A Leading Cause of Color Cursor Cursing
° d ONLN d ( ç < ú r *Imaging ° d ONLN d 0 çÄ ú˛ ( ∏ûM.IM.ColorCursor
° d ONLN d A ® < ¥ t ( – Z Revised by: ° d ONLN d M ® Ñ ¥ ¡ )H
Alan Mimms ° d ONLN d X ®æ ¥˛ ( –‹ October 1989 ° d ONLN d e ¥ < ¿ q ( ‹ Z Written by: ° d ONLN d q ¥ Ñ ¿ ¡ )H
Alan Mimms ° d ONLN d | ¥Õ ¿˛ ( ‹Î June 1989 ° d ONLN d Ü Ã < ÿù ( Ù ZIWorking with color cursors you create from scratch can cause headaches. ° d ONLN d œ Ãù ÿ˛ ( ÙªThis Technical Note ° d ONLN d „ ÿ < ‰ Ç ( Zmay help a bit. ° d ONLN d Û Â < Ò œ *
Changes since June 1989: ° d ONLN d  œ Òw )ì" Added a warning about purgeable ,
Courier ° d ONLN d- ‰w ° )®'clut' ° d ONLN d3 ° Ò’ )* resources. X ° d ONLN d?
< Ò (2 Z'If you’re building an application that ° d ONLN df
Ò˛ )µ4creates color cursors, you may encounter some quirks ° d ONLN dõ <"¿ (> ZOpresent in Color QuickDraw that manifest themselves in hard-to-understand ways. ° d ONLN dÎ. <: º *If your cursor is, say, 15 ° d ONLN d. º:˛ )Ä@pixels tall and 9 pixels wide, you might be tempted to use these ° d ONLN dG; <G Ç (c Zvalues for the ° d ONLN dV: ÇF › )F
'clut' ° d ONLN d≥ˇ ã ‹ )* resource using ° d ONLN d√˛ ‹
" )Q
_GetCTable ° d ONLN dÕˇ" « )F , you should make sure that the ° d ONLN dÌ˛«
Ò )•'clut' ° d ONLN dÛˇÒ ˛ )* is ° d ONLN d˜ < (3 Z,marked non-purgeable while the color cursor ° d ONLN d# ˛ )›/is in use. If you do not take this precaution, ° d ONLN dS <$ ¥ (@ Zbombs will occur if your ° d ONLN dl ¥# fi )x'clut' ° d ONLN dr fi$Ü )*$ gets purged at in inopportune time. ◊ X◊
(Ï Z'A Leading Cause of Color Cursor Cursing (Ï1 ) of 1 ˇ ° ¿Ù%%DSIDICT:_cv
currentdict /bu known {bu}if
userdict /_cv known not{userdict /_cv 30 dict put}if
_cv begin
/bdf{bind def}bind def
currentscreen/cs exch def/ca exch def/cf exch def
/setcmykcolor where{/setcmykcolor get /cvcmyk exch def}{/cvcmyk{1 sub 4 1 roll 3{3 index add neg dup 0 lt{pop 0}if 3 1 roll}repeat setrgbcolor pop}bdf }ifelse
/ss{//cf //ca //cs setscreen}bdf
/stg{ss setgray}bdf
/strgb{ss setrgbcolor}bdf
/stcmyk{ss cvcmyk}bdf
/min1{dup 0 eq{pop 1}if}bdf
end
currentdict /bn known {bn}if
† ø ◊# ˇ ˇˇˇˇ # ◊ † Ç
/ Z Å#
0Ià:µú9 " { ˇˇˇˇˇˇˇˇ # † ƒ ° d
ONLN f ˛ † å ° d 1drw2 … -·_ Ä ˇˇˇˇˇˇ è ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˙ ó@ † ò , Times
. R… R… +]BNew Technical Notes † ô ° d drw2 : °„ † ó ° d 1drw2 eÙ Ä ˇˇˇˇˇˇ P ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä E¿ † ò
( {ïDeveloper Support † ô ° d drw2 : °„ † ó ° d `drw2 - Ô ˇˇˇˇˇˇ K Ô - Z f f Z ° d 1drw2 ¿˙È ˇˇˇˇˇˇ K ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : 0 ° ö ˇÙ Ä † ò
0 ( UÔ † ô ° d drw2 : °„ † ó ° d 1drw2 ÔÊ˙ ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˝Ä † ò
+& ® † ô ° d drw2 : °„ † ó ° d 1drw2  -¯ y ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä % † ò
( Z \ Macintosh † ô ° d drw2 : °„ † ó † ç ° d drw2 D † É
IR . ° d ONLN d n < Å ( õ ZColor Manager Q&As
° d ONLN d Ä < è r *Imaging ° d ONLN d Äe è˛ ( ´ÉM.IM.ColorMgr.Q&As
° d ONLN d . õ < ß t ( √ Z Revised by: ° d ONLN d : õ Ñ ß ˇ )HDeveloper Support Center ° d ONLN d S õæ ߲ ( √‹ October 1992 ° d ONLN d ` ß < ≥ q ( œ Z Written by: ° d ONLN d l ß Ñ ≥ ˇ )HDeveloper Support Center ° d ONLN d Ö ßæ ≥˛ ( œ‹ October 1990 ° d ONLN d í ø < À ⁄ ( Á Z This Technical Note contains a ° d ONLN d ± ø ⁄ À˛ )û9collection of Q&As relating to a specific topic—questions ° d ONLN d Î À < ◊† ( Û ZGyou’ve sent the Developer Support Center (DSC) along with answers from ° d ONLN d2 À† ◊˛ ( Ûæthe DSC engineers. ° d ONLN dE ◊ < „ u ( ˇ Z
While DSC ° d ONLN dO ◊ u „˛ )9Lengineers have checked the Q&A content for accuracy, the Q&A Technical Notes ° d ONLN dú „ < Ô q ( Z don’t have ° d ONLN dß „ q Ô˛ )5Qthe editing and organization of other Technical Notes. The Q&A function is to get ° d ONLN d˘ Ô < ˚ Ÿ ( Z new technical information and ° d ONLN d Ô Ÿ ˚˛ )ù6updates to you quickly, saving the polish for when the ° d ONLN dN ˚ < (# Z,information migrates into reference manuals. ° d ONLN d{ < k *:Q&As are now included with Technical Notes to make access ° d ONLN dµk ˛ (;â to technical updates easier for ° d ONLN d’ <+. (G Z/you. If you have comments or suggestions about ° d ONLN d .+˛ )Ú*Q&A content or distribution, please let us ° d ONLN d/+ <7 \ (S Zknow ° d ONLN d4+ \7˛ ) Iby sending an AppleLink to DEVFEEDBACK. Apple Partners may send technical ° d ONLN d~7 <Ci (_ Z9questions about Q&A content to DEVSUPPORT for resolution. ° d ONLN d∏O <[« *NNew Q&As and Q&As revised this month are marked with a bar in the side margin. "n Ü XÜ
° d ONLN dÄ <èç *4.Color Manager search and complement procedures
° d ONLN d6è <õ b * Written: ° d ONLN d?è àõ ¨ )L10/7/91 ° d ONLN dGõ <ß Å (√ ZLast reviewed: ° d ONLN dVõ àß ¨ )L11/6/91 ° d ONLN d^≥ <ø Ö (€ Z The AddComp ° d ONLN dj≥ Öø˙ )IHcomplement procedure description in Inside Macintosh Volume V, pages 145 ° d ONLN d≤≥˙ø˛ (€- ° d ONLN d≥ø <À
(Á Z*147, is vague. The last paragraph on page ° d ONLN d›ø
À˛ )—-V-146 states, “Complement procedures work the ° d ONLN d À <◊Q (Û Z:same as search procedures,” but SearchProc is a function, ° d ONLN dEÀQ◊˛ (Ûo!CompProc is a procedure, and each ° d ONLN dg◊ <„ (ˇ ZYhave a different number of parameters. What else does CompProc need as input and on exit? ° d ONLN d¡„ <Ô N * ___ ° d ONLN d≈˚ < ‰ * CompProc should be declared as ° d ONLN d‰˚ ‰˛ )®2a Pascal FUNCTION that returns a Boolean. The code ° d ONLN d <v (/ Z?performs a CLR.B for the return value of CompProc, so treat it ° d ONLN dVv˛ (/îlike SearchProc. CompProc ° d ONLN dp < æ (; ZQonly uses one parameter since its one parameter is a VAR, which means it will be ° d ONLN d¡æ ˛ (;‹
replaced with ° d ONLN dœ <+’ (G ZVthe correct complementary color. SearchProc returns an index in its second parameter, ° d ONLN d% ’+˛ (GÛwhich is ° d ONLN d.+ <7 Ÿ (S Z why it needs a second parameter. ◊ X◊
*ôColor Manager Q&As (Ï1 ) of 2 ˇ ° ¿Ù%%DSIDICT:_cv
currentdict /bu known {bu}if
userdict /_cv known not{userdict /_cv 30 dict put}if
_cv begin
/bdf{bind def}bind def
currentscreen/cs exch def/ca exch def/cf exch def
/setcmykcolor where{/setcmykcolor get /cvcmyk exch def}{/cvcmyk{1 sub 4 1 roll 3{3 index add neg dup 0 lt{pop 0}if 3 1 roll}repeat setrgbcolor pop}bdf }ifelse
/ss{//cf //ca //cs setscreen}bdf
/stg{ss setgray}bdf
/strgb{ss setrgbcolor}bdf
/stcmyk{ss cvcmyk}bdf
/min1{dup 0 eq{pop 1}if}bdf
end
currentdict /bn known {bn}if
† ø r ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘
° d ONLN d ) 8@ *'*Using ResEdit to get Apple icon RGB values
° d ONLN d + 8 D > * Written: ° d ONLN d 4 8 d D Ç )L1/7/92 ° d ONLN d ; D P ] ( l 6Last reviewed: ° d ONLN d J D d P Ç )L8/1/92 ° d ONLN d Q \ h^ ( Ñ 6=I am trying to find the RGB values for Apple's standard icon ° d ONLN d é \^ h⁄ ( Ñ|colors. I can’t find this ° d ONLN d ® h tF ( ê 6@information in any documentation. Is this information available? ° d ONLN d È t Ä * * ___ ° d ONLN d Ì å òß *TWhile the RGB values for the standard Apple icon colors (and other standard palette ° d ONLN dA åß ò⁄ ( ¥≈ colors) are ° d ONLN dM ò § fi ( ¿ 6)not explicitly documented, they are easy ° d ONLN dv ò fi §⁄ )Δ3to obtain with ResEdit 2.1.1. In any resource file, ° d ONLN d™ § ∞ Û ( à 6.create and open a new 'pltt' resource. Choose ° d ONLN dÿ § Û ∞⁄ )€-Load Colors from the pltt menu and pick Apple ° d ONLN d ∞ º ø ( ÿ 6$Icon Colors, and a standard palette ° d ONLN d* ∞ ø º⁄ )ß<will be created. Selecting a color will reveal its component ° d ONLN dg º » : ( ‰ 6values. ° d ONLN do ‘ ‡ú *PResEdit 2.1.1 is available on the latest Developer CD Series disc and from APDA.
° d ONLN d¿ ¯ c *'.Macintosh Color Manager versus Palette Manager
° d ONLN dÔ > * Written: ° d ONLN d¯ d Ç )L1/1/90 ° d ONLN dˇ ] (; 6Last reviewed: ° d ONLN d d Ç )L8/1/92 ° d ONLN d+ 7 Z (S 6 When should ° d ONLN d!+ Z7⁄ )BJthe Macintosh Color Manager be used and when should the Palette Manager be ° d ONLN dl7 C 3 (_ 6used? ° d ONLN drC O * * ___ ° d ONLN dv[ gV *CThe Palette Manager is by far the friendlier and more versatile of ° d ONLN dπ[Vg⁄ (Étthe two if your application ° d ONLN d’g s° (è 6Xuses different colors than the default system colors. It provides all the functionality ° d ONLN d-g°s⁄ (èø you need to ° d ONLN d9s å (õ 6Ncustomize and animate the colors in your application. You shouldn’t ever need ° d ONLN dáså⁄ (õ™to use the Color ° d ONLN dò ãå (ß 6IManager unless you require custom color search and complement functions. ° d ONLN d·åã⁄ (ß™When using the ° d ONLN dã óñ (≥ 6PPalette Manager, applications will maintain their respective color environments ° d ONLN d@ãñó⁄ (≥¥safely as they ° d ONLN dOó £H (ø 67move back and forth from foreground to background, and ° d ONLN dÜóH£⁄ (øffrom one screen to another. ° d ONLN d¢£ ب (À 6PAccomplishing this with the Color Manager calls is not worth the effort or very ° d ONLN dÚ£¨Ø⁄ (À safe. For ° d ONLN d¸Ø ªŸ (◊ 6]additional information, see the Palette Manager chapter in Inside Macintosh Volumes V and VI. ◊ 4◊˘
ONLN f ˛ † å ° d 1drw2 … -·_ Ä ˇˇˇˇˇˇ è ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˙ ó@ † ò , Times
. R… R… +]BNew Technical Notes † ô ° d drw2 : °„ † ó ° d 1drw2 eÙ Ä ˇˇˇˇˇˇ P ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä E¿ † ò
( {ïDeveloper Support † ô ° d drw2 : °„ † ó ° d `drw2 - Ô ˇˇˇˇˇˇ K Ô - Z f f Z ° d 1drw2 ¿˙È ˇˇˇˇˇˇ K ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : 0 ° ö ˇÙ Ä † ò
0 ( UÔ † ô ° d drw2 : °„ † ó ° d 1drw2 ÔÊ˙ ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˝Ä † ò
+& ® † ô ° d drw2 : °„ † ó ° d 1drw2  -¯ y ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä % † ò
( Z \ Macintosh † ô ° d drw2 : °„ † ó † ç ° d drw2 D † É
IR . ° d ONLN d n < Å ( õ ZColor QuickDraw Q&As
° d ONLN d Ä < è r *Imaging ° d ONLN d Äk è˛ ( ´âM.IM.ColorQD.Q&As
° d ONLN d / õ < ß t ( √ Z Revised by: ° d ONLN d ; õ Ñ ß ˇ )HDeveloper Support Center ° d ONLN d T õ¥ ߲ ( √“
December 1992 ° d ONLN d b ß < ≥ q ( œ Z Written by: ° d ONLN d n ß Ñ ≥ ˇ )HDeveloper Support Center ° d ONLN d á ßæ ≥˛ ( œ‹ October 1990 ° d ONLN d î ø < À ⁄ ( Á Z This Technical Note contains a ° d ONLN d ≥ ø ⁄ À˛ )û9collection of Q&As relating to a specific topic—questions ° d ONLN d Ì À < ◊† ( Û ZGyou’ve sent the Developer Support Center (DSC) along with answers from ° d ONLN d4 À† ◊˛ ( Ûæthe DSC engineers. ° d ONLN dG ◊ < „ u ( ˇ Z
° d ONLN dˇå <õâ *4/Disabling Macintosh Color QuickDraw for testing
° d ONLN d/õ <ß x *
Date written: ° d ONLN d=õ àß ¨ )L9/14/92 ° d ONLN dEß <≥ Å (œ ZLast reviewed: ° d ONLN dTß à≥ ¨ )L11/1/92 ° d ONLN d\ø <À5 (Á Z3Is there an easy way to disable Color QuickDraw on ° d ONLN dèø5À˛ )˘*a Macintosh? I want to do this for testing ° d ONLN d∫À <◊fi (Û ZVour application, to make sure it works correctly on a machine without Color QuickDraw. ° d ONLN d◊ <„ N * ___ ° d ONLN dÔ <˚Ø *MThere’s no easy, or perhaps even hard way to disable features built into the ° d ONLN dbÔØ˚˛ (Õsystem software ° d ONLN dr˚ <¬ (# ZTyour particular machine requires. It’s designed to work well, not to be toggle-able. ° d ONLN d« < Œ * Even the hard way isn’t a sure ° d ONLN dÊ Œ ˛ )í=thing—trying to patch out all the Color QuickDraw traps could ° d ONLN d$ <+k (G Z>confuse the rest of the system software, which internally may ° d ONLN db k+˛ (Gâ use undocumented routines to ° d ONLN d+ <7 û (S Zaccomplish its tasks. ° d ONLN dïC <OÅ *>The easiest way to test on non-Color QuickDraw machines is to ° d ONLN d”CÅO˛ (küget one. Fortunately, the ° d ONLN dÌO <[ í (w Zmachines without ° d ONLN d˛O í[˛ )VGColor QD are the lowest end of the Macintosh price spectrum—such as the ° d ONLN dF[ <g¢ (É ZEMacintosh Classic, PowerBook 100, and Macintosh SE. You can probably ° d ONLN dã[¢g˛ (É¿rent or borrow one ° d ONLN dûg <s( (è Z5of these if the prices don’t fit your current budget.
° d ONLN d‘ã <öÌ *'?Using a Macintosh PICT file that’s larger than available memory
° d ONLN dö <¶ b * Written: ° d ONLN d ö ච¨ )L6/18/90 ◊ X◊
userdict /_cv known not{userdict /_cv 30 dict put}if
_cv begin
/bdf{bind def}bind def
currentscreen/cs exch def/ca exch def/cf exch def
/setcmykcolor where{/setcmykcolor get /cvcmyk exch def}{/cvcmyk{1 sub 4 1 roll 3{3 index add neg dup 0 lt{pop 0}if 3 1 roll}repeat setrgbcolor pop}bdf }ifelse
/ss{//cf //ca //cs setscreen}bdf
/stg{ss setgray}bdf
/strgb{ss setrgbcolor}bdf
/stcmyk{ss cvcmyk}bdf
/min1{dup 0 eq{pop 1}if}bdf
end
currentdict /bn known {bn}if
† øz ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘
° d ONLN d ) ] *Last reviewed: ° d ONLN d d ) à )L9/24/91 ° d ONLN d 5 A= ( ] 69How can I read a 2 MB PICT file into only 1 MB of memory? ° d ONLN d Q A M * * ___ ° d ONLN d U Y ej *EYou can’t read it in since you don’t have enough memory, but drawing ° d ONLN d ö Yj e⁄ ( Åàthe picture contained in ° d ONLN d ≥ e q ê ( ç 6the file using a technique ° d ONLN d Œ e ê q⁄ )xBcalled “spooling” increases your chances of using a 2 MB PICT file ° d ONLN d q } 2 ( ô 6with ° d ONLN d q 2 }Ω )F1 MB memory. Spooling is documented in the Color QuickDraw chapter of ° d ONLN d\ qΩ }⁄ ( ô€Inside ° d ONLN dc } â I ( • 6 Macintosh ° d ONLN dl } I â « )1 Volume V (pages 88–89).
° d ONLN dÖ ° ∞6 ( Ã 6+Getting a single scan line from a PICT file
° d ONLN d± ∞ º > * Written: ° d ONLN d∫ ∞ d º à )L6/18/90 ° d ONLN d¬ º » ] ( ‰ 6Last reviewed: ° d ONLN d— º d » à )L9/24/91 ° d ONLN dŸ ‘ ‡K ( ¸ 6CIs there any way to obtain a particular scan line from a PICT file? ° d ONLN d ‡ Ï * * ___ ° d ONLN d! ¯ À *VA PICT file may contain more than just pixmaps, so getting one scan line out of it is ° d ONLN dw ¯À⁄ ( Ènot ° d ONLN d{ · (, 6*possible. The file may also contain other ° d ONLN d• ·⁄ )…2elements that overlap, such as rects and arcs. The ° d ONLN dÿ 0 (8 6only ° d ONLN d› 0 ⁄ )Yway to obtain a single line is to draw it off-screen and then, once the whole image is in ° d ONLN d7 ( (D 6/memory, you can go and study individual pixels.
° d ONLN dg@ O* *''Determining pixel depth from PICT files
° d ONLN dèO [ > * Written: ° d ONLN dòO d[ à )L6/20/90 ° d ONLN d†[ g ] (É 6Last reviewed: ° d ONLN dØ[ dg à )L9/17/91 ° d ONLN d∑s < (õ 6>How do you find out the pixel size of a PICT file on the disk? ° d ONLN dˆ ã * * ___ ° d ONLN d˙ó £z *GA picture is by nature independent of depth. For example, you can have ° d ONLN dAóz£⁄ (øòa picture containing ° d ONLN dV£ Øk (À 6EDrawRects and LineTos and therefore lacking any info regarding depth. ° d ONLN dúª «x *KOn the other hand, if the picture you are looking at has pixmap opcodes in ° d ONLN dÁªx«⁄ („ñit, then each pixmap ° d ONLN d¸« ”w (Ô 6Icontains its own pixel size and in this case a picture can have a number ° d ONLN dE«w”⁄ (Ôïof depths associated ° d ONLN dZ” fl : (˚ 6with it. ° d ONLN dcÎ ˜ Ÿ *+If you want to see the pixel size for each ° d ONLN déÎ Ÿ˜⁄ )¡6pixmap opcode in a picture, replace all the bottleneck ° d ONLN d≈˜ ¿ ( 6\routines and every time the bitsProc is called you can see the pixmap and get the info out. ° d ONLN d!˜¿⁄ ( fiSince ° d ONLN d' ñ (+ 6 the picture is in a file, you ° d ONLN dE ñ⁄ )~Acan use the spooling technique described in the QuickDraw chapter ° d ONLN dá $ (7 6in ° d ONLN dä $ u ) Inside Macintosh ° d ONLN dö u ø )Q Volume V. Be ° d ONLN d® ø⁄ )J;ready to deal with multiple, possibly different, pixmaps as ° d ONLN d‰ 's (C 6Iwell as direct pixmaps if the picture was created under 32-bit QuickDraw. ° d ONLN d.3 ? è *”KnowsPICT,” on the ° d ONLN dB3 è? ¯ )wDeveloper CD Series ° d ONLN dU3 ¯?» )i* disc, extracts this kind of information. ° d ONLN d3»?⁄ )–The ° d ONLN dÉ? K= (g 6?System 7.0 Picture Utilities package gets this information too.
° d ONLN d√c r *' Direct RGB PICT file compression
° d ONLN d‰r ~ > * Written: ° d ONLN dÌr d~ é )L10/24/90 ° d ONLN dˆ~ ä ] (¶ 6Last reviewed: ° d ONLN d~ dä à )L2/14/91 ◊ 4◊˘
° d ONLN d < ) ( E ZVHow are bits packed in direct RGB PICT files created by 32-Bit QuickDraw? I looked at ° d ONLN d V )˛ ( Ethe ° d ONLN d Z ) < 5¿ ( Q ZGMacintosh Technical Note “Things You Wanted to Know About _PackBits…”, ° d ONLN d ° )¿ 5˙ ( Qfi but this run ° d ONLN d ≠ )˙ 5˛ ):- ° d ONLN d Æ 5 < A* ( ] Z2length encoded compression is clearly inefficient ° d ONLN d ‡ 5* A˛ )Ó+for cases where pixelSize is greater than 8 ° d ONLN d A < M T ( i Zbits. ° d ONLN d A T M˛ )XI write software for machines other than Macintosh that decodes PICT files; therefore, I ° d ONLN dk M < YC ( u Z5cannot issue any QuickDraw calls such as _unpackBits. ° d ONLN d° Y < e N * ___ ° d ONLN d• q < } z *
You’re quite ° d ONLN d≤ q z }˛ )>Pright; compressing direct pixels using straight run-length encoding doesn’t work ° d ONLN d } < âu ( • ZAvery well. Fortunately, direct pixel maps aren’t compressed this ° d ONLN dD }u Ⲡ( •ìway. Compression schemes ° d ONLN d] â < ï ì ( ± Zare discussed in ° d ONLN dn â ì ï Á )WInside Macintosh ° d ONLN d~ â Á ïM )T Volume VI in the ° d ONLN dê âM ï˛ )f section titled “The New OpCodes: ° d ONLN d± ï < ° ô ( Ω ZExpanded Format.” ° d ONLN d√ ≠ < πÏ *WIn short, if the packType field holds the value 1, then no compression is done at all. ° d ONLN d ≠Ï π˛ ( ’
The ° d ONLN d π < ≈’ ( · ZWcomplete pixel image is saved in the PICT. If the packType field holds the value 2 and ° d ONLN du π’ ≈˛ ( ·Û the pixel ° d ONLN d ≈ < —¯ ( Ì Zbmap is 32-bits per pixel, then all that’s done is that the alpha-channel byte is removed. So this: ,
Courier
° d ONLN d‚ › < Ë' */ 00 FF FF FF 00 FF FF FF
° d ONLN d Û < ˇ é *is compressed to:
° d ONLN d$ < *) FF FF FF FF FF FF
° d ONLN dN! <- ° *If the packType field ° d ONLN dd! °-˛ )eIholds the value 3 and the pixel map is 16 bits per pixel, then run-length ° d ONLN dÆ- <9 j (U Z encoding ° d ONLN d∑- j9˛ ).Sis done, but not through PackBits. Instead, a run-length encoding algorithm private ° d ONLN d 9 <E (a Z%to QuickDraw is used. This algorithm ° d ONLN d09E˛ )«/is very similar to PackBits, but where PackBits ° d ONLN d`E <Q œ (m Z compresses runs of bytes, this ° d ONLN dE œQ˛ )ì=routine compresses runs of words. The format of the resulting ° d ONLN dΩQ <] _ (y Zdata is ° d ONLN d≈Q _]˛ )#Nexactly the same as described in the Technical Note “Things You Wanted to Know ° d ONLN d] <ii (Ö Z=About _PackBits…”, but you’ll get words instead. To build on ° d ONLN dQ]ii˛ (Öá the example in this Tech Note, ° d ONLN dpi <u[ (ë Z?lets say the 16-bit pixel image begins with these pixel values:
? 2A2A 2222 AAAA AAAA AAAA AAAA AAAA AAAA AAAA AAAA AAAA AAAA ° d ONLN d0ü <™Ω *MAfter being packed by QuickDraw’s internal compression routine, this becomes: ° d ONLN d~≥ <æ s * FE AAAA ° d ONLN däΩ <» • *
02 8080 0000 2A2A ° d ONLN d†« <“ s *
FD AAAA ° d ONLN d¨— <‹ æ *
03 8080 0000 2A2A 2222 ° d ONLN d«€ <Ê s *
F7 AAAA
° d ONLN d”Ò <˝ F *or
° d ONLN d÷ <Ü *B FEAA AA02 8080 0000 2A2A FDAA AA03 8080 0000 2A2A 2222 F7AA AA ° d ONLN d < h *
< * * * * *
° d ONLN dV) <5 **where the asterisks mark the flag-counter ° d ONLN dÄ)5˛ )À2bytes. Notice that you can’t assume that the pixel ° d ONLN d≥5 <AQ (] Z:values are word-aligned. PackBits packs data 127 bytes at ° d ONLN dÌ5QA˛ (]o%a time, though it will do this for up ° d ONLN d A <MT (i Z;to 32,767 total bytes. Similarly, the internal compression ° d ONLN d NATM˛ (ir!routine packs data 127 words at a ° d ONLN d pM <Y T (u Ztime. ° d ONLN d ve <q ° *If the packType field ° d ONLN d åe °q˛ )eIholds the value 4 and the pixel map is 32-bits per pixel, then run-length ° d ONLN d ÷q <} ÷ (ô Z encoding via PackBits is done, ° d ONLN d ıq ÷}˛ )ö:but only after some preprocessing is done. QuickDraw first ° d ONLN d
0} <⪠(• ZNrearranges the color components of the pixels so that each color component of ° d ONLN d
~}ªâ˛ (•Ÿevery pixel is ° d ONLN d
çâ <ï z (± Z
consecutive. ° d ONLN d
öâ zï˛ )>PSo the following four pixels (the row below the pixel values indicates a = alpha ° d ONLN d
Îï <°Q (Ω Z=channel, r = red, g = green, b = blue, and the pixel offset): ◊ X◊
*/Color QuickDraw Q&As (Ïˇ3 ) of 31 ˇ
◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘ ,
Courier
° d ONLN d (N *> 00 FF FF FF 00 FF C0 00 00 FF 80 00 00 C0 80 00 ° d ONLN d ? ' 2N *
> a0 r0 g0 b0 a1 r1 g1 b1 a2 r2 g2 b2 a3 r3 g3 b3
° d ONLN d ~ = I ã *is rearranged to become:
° d ONLN d ó U `
*1 FF FF FF C0 FF C0 80 80 FF 00 00 00 ° d ONLN d … _ j
picture that ° d ONLN d Ÿp O|⁄ )7OI created to show how the different packing schemes change the resulting pixmap ° d ONLN d
)| àÜ (§ 6Oopcode data. First I created a direct RGB pixmap and drew three lines into it. ° d ONLN d
x|Üà⁄ (§§The first line is 8 ° d ONLN d
åà îö (∞ 6Ppixels long with a color of {0x1111,0xAAAA, 0x7777}, the third line is 8 pixels ° d ONLN d
‹àöî⁄ (∞∏ of {0xFFFF, ° d ONLN d
Ëî † C (º 60x3333, ° d ONLN d
î C†⁄ )+S0xBBBB} and the line in between is two pixels of the first color then two pixels of ° d ONLN d D† ¨0 (» 6;the second color and so on until you make 8 pixels. Then I ° d ONLN d †0¨⁄ (»N"created a picture made of CopyBits ◊ 4◊˘
° d ONLN d < )∏ ( E ZJcalls copying the same lines but using different packing schemes. Finally ° d ONLN d J ∏ )˛ ( E÷ I dumped the ° d ONLN d W ) < 5â ( Q ZDcontents and the result is what you see here. I have put comments I ° d ONLN d õ )â 5˛ ( Qßthink help make it clear ° d ONLN d ¥ 5 < A> ( ] Z5how the packing scheme of choice changes the results. ° d ONLN d Í M < Y D *I ° d ONLN d Ï M D Y € ) recommend that you have the ° d ONLN d M € Y. )óInside Macintosh ° d ONLN d M. Y˛ )S& Volume V QuickDraw chapter at hand to ° d ONLN d? Y < e\ ( Å Z<check the opcodes and data associated with them. If you had ° d ONLN d{ Y\ e| ( ÅzInside ° d ONLN dÇ Y| e≠ ) Macintosh ° d ONLN dã Y≠ e˛ )1 Volume VI then ° d ONLN dõ e < q ‰ ( ç Z you wouldn’t need to also check ° d ONLN dª e ‰ q˛ )®3the 32-Bit QuickDraw docs for the direct RGB pixmap ° d ONLN dÔ q < }~ ( ô Z=opcodes. The Technical Note “Things You Wanted To Know about ° d ONLN d, q~ }˛ ( ôú_PackBits…” gives details ° d ONLN dF } < â Ê ( • Z#on how the packed data is arranged. ,
L08 /* third line same as first */ ° d ONLN d ˘ w *
F900 F9FF F933 F9BB ° d ONLN d1 S *
?00FF /* end of PICT */
° d ONLN dq % *9A section of the code that produces this picture follows:
° d ONLN d´1 < *4 RGBColor oneColor = {0x1111, 0xaaaa, 0x7777}, ° d ONLN d‡; F *
2 twoColor = {0xffff,0x3333,0xbbbb}; ° d ONLN dO Zô *M SetGWorld(GgwPtr, nil); /* set the off-screen GWorld */ ° d ONLN dac n Ô *+ if ( LockPixels(GgwPtr -> portPixMap) ) ° d ONLN dçm x 1 *
{ ° d ONLN dìÅ å € *' EraseRect(&(GgwPtr->portRect)); ° d ONLN dªï † ∏ * RGBForeColor(&oneColor); ° d ONLN d‹ü ™ | *
I CopyBits((*(GgwPtr -> portPixMap)),(*(GgwPtr -> portPixMap)), ° d ONLN d% Å < å *
) &rr,&localR,srcCopy,nil); ° d ONLN dO ã < ñ Ø *
ClosePicture(); ° d ONLN dg ï < † ˇ *
' UnlockPixels(GgwPtr -> portPixMap); ° d ONLN dè ü < ™ U *
}
° d ONLN dï µ < ¡ ] *X-Ref: ° d ONLN dú ¡ < Õ û * “Color QuickDraw,” ° d ONLN dÆ ¡ û Õ ˘ )b Inside Macintosh, ° d ONLN d¡ ¡ ˘ Õ) )[Volume V ° d ONLN d Õ < Ÿ ° ( ı Z“Color QuickDraw,” ° d ONLN d› Õ ° Ÿ ˆ )eInside Macintosh, ° d ONLN dÓ Õ ˆ Ÿ- )U
Volume VI ° d ONLN d˘ Ÿ < Â∞ ( ZEMacintosh Technical Note “Things You Wanted To Know about _PackBits…”
° d ONLN d? ˝ < Δ *'4BitMapToRgn for non-Color QuickDraw Macintosh models
° d ONLN dt < b * Written: ° d ONLN d} à ¨ )L11/9/90 ° d ONLN dÖ <$ Å (@ ZLast reviewed: ° d ONLN dî à$ ¨ )L2/20/91 ° d ONLN dú0 <<† (X ZEIs _BitmapToRegion available on any pre-System 7 non-Color QuickDraw ° d ONLN d·0†<˛ (Xæconfigurations such ° d ONLN dı< <H ˆ (d Z'as the Macintosh Classic, Plus, or SE? ° d ONLN d < ˆH˛ )∫9If not, is source or a library module available so that I ° d ONLN dVH <T (p ZEdon’t have to take the time and compatibility risk of rolling my own? ° d ONLN dúT <` N * ___ ° d ONLN d†l <x ƒ *BitMapToRegion works on ° d ONLN d∏l ƒx˛ )à;pre-color Macintosh systems. You can license BitMapToRegion ° d ONLN dÙx <Ñ S († Zfrom ° d ONLN d˘ê <ú § * Software Licensing ° d ONLN dú <® ∞ * Apple Computer, Inc. ° d ONLN d)® <¥ “ * 20525 Mariani Ave. MS:38-I ° d ONLN dH¥ <¿ Ø * Cupertino, CA 95014 ° d ONLN d`¿ <à « * AppleLink: SW.LICENSE ° d ONLN dzà <ÿ ¥ * Phone:(408) 974-4667 ◊ X◊
° d ONLN d ) 8s *'0Macintosh QuickDraw pixel map stack requirements
° d ONLN d 1 8 D > * Written: ° d ONLN d : 8 d D à )L12/3/90 ° d ONLN d B D P ] ( l 6Last reviewed: ° d ONLN d Q D d P à )L5/21/91 ° d ONLN d Y \ h § ( Ñ 6 What are the guidelines for ° d ONLN d u \ § h⁄ )å7determining how much of an image CopyBits can copy to a ° d ONLN d ≠ h t± ( ê 6ZMacintosh pixel map at one time, given a particular set of characteristics for the source ° d ONLN d h± t⁄ ( êœmap and ° d ONLN d t Ä[ ( ú 6Athe destination map and given how much stack space is available? ° d ONLN dP t[ Ä⁄ ( úyFor example, say that we ° d ONLN di Ä å+ ( ® 68have an 8-bit-deep pixmap to be copied to a 32-bit-deep ° d ONLN d° Ä+ å⁄ ( ®I pixMap using the ditherCopy mode ° d ONLN d¬ å òG ( ¥ 6>and expanded by a factor of 4, and we have 45K of stack space. ° d ONLN d ò § * * ___ ° d ONLN d ∞ º– *XCopyBits’ stack requirement depends on the width of each scan line (rowBytes). The rule ° d ONLN d] ∞– º⁄ ( ÿÓof ° d ONLN d` º » ” ( ‰ 6(thumb is that you need at least as much ° d ONLN dà º ” »⁄ )ª4stack as the rowBytes value in your image (which can ° d ONLN dΩ » ‘N ( 6>be huge with 32-Bit QuickDraw), with the following additional ° d ONLN d˚ »N ‘⁄ ( l modifiers: Add an additional ° d ONLN d ‘ ‡¬ ( ¸ 6[rowBytes for dithering; add an additional rowBytes for any stretching (source rect != dest ° d ONLN ds ‘¬ ‡⁄ ( ¸‡rect); ° d ONLN dz ‡ ÏÉ ( 6Iadd an additional rowBytes for any color map changing; add an additional ° d ONLN d√ ‡É Ï⁄ (°rowBytes for any ° d ONLN d‘ Ï ¯ ‰ ( 6,color aliasing. The stack space you need is ° d ONLN d Ï ‰ ¯⁄ )Ã1roughly five times the rowBytes of your image. In ° d ONLN d2 ¯ c ( 6Dgeneral, you’re better off processing narrower scan lines. Reducing ° d ONLN dv ¯c⁄ ( Åthe vertical size will not ° d ONLN dë (, 62affect stack requirements. Narrow, tall bands (if ° d ONLN d√ ⁄ )Ù'you can use them) will reduce the stack ° d ONLN dÎ Y (8 6
requirements.
° d ONLN d˘4 Cù *'7Color and non-Color QuickDraw trap dispatch differences
° d ONLN d1C O > * Written: ° d ONLN d:C dO à )L1/28/91 ° d ONLN dBO [ ] (w 6Last reviewed: ° d ONLN dQO d[ à )L2/13/91 ° d ONLN dYg s¿ (è 6RWhy does a call to RGBForeColor cause a corruption of the stack without resulting ° d ONLN d´g¿s⁄ (èfiin an ° d ONLN d±s m (õ 6Bunimplemented trap error on non-Color QuickDraw Macintosh systems? ° d ONLN dÙ ã * * ___ ° d ONLN d¯ó £ ¢ * The trap dispatcher on Color ° d ONLN dó ¢£⁄ )ä<QuickDraw and non-Color QuickDraw machines are different. If ° d ONLN dR£ Ø Ö (À 6you look at page 89 of ° d ONLN di£ ÖØ ÷ )mInside Macintosh ° d ONLN dy£ ÷Ø )Q Volume ° d ONLN dÅ£Ø⁄ )+-I, you’ll see the toolbox trap word format as ° d ONLN dØØ ªï (◊ 6Jit was in the days before Color QuickDraw. Bit 9 was “reserved for future ° d ONLN d˘Øïª⁄ (◊≥ use” and was ° d ONLN dª « t („ 6ignored by the trap ° d ONLN dª t«⁄ )\Jdispatcher, and so it was normally set to 0. That means that valid toolbox ° d ONLN de« ” ù (Ô 6 traps could either look like ° d ONLN dÇ« ù”⁄ )Ö:$A8XX or $A9XX as long as the auto-pop bit was turned off. ° d ONLN dΩ” fl (˚ 65Color QuickDraw machines have a trap dispatcher that ° d ONLN dÚ”fl⁄ (˚9(uses that reserved bit to allow for more ° d ONLN dfl Î ( 64trap words, and therefore it has a much larger trap ° d ONLN dOflÎ⁄ )Ô*dispatch table. Color QuickDraw traps have ° d ONLN dzÎ ˜N ( 6?that reserved bit set, so those traps look like $AAXX or $ABXX. ° d ONLN d∫ … *TWhen a non-Color QuickDraw machine tests to see if a trap is implemented or not, it ° d ONLN d …⁄ (+Ájust ° d ONLN d | (7 6Pchecks the trap dispatch table to see if a routine is implemented for that trap ° d ONLN d c|⁄ (7öor not. Because the ° d ONLN d w ' ] (C 6reserved bit is ° d ONLN d á ]'⁄ )EKignored, trap words that look like $AAXX are treated as equivalent to $A8XX ° d ONLN d ”' 3 b (O 6and trap words ° d ONLN d ‚' b3⁄ )JJthat look like $ABXX are treated as equivalent to $A9XX. The trap word for ° d ONLN d
-3 ? ® ([ 6RGBForeColor is $AA14. If ° d ONLN d
G3 ®?⁄ )ê7you call RGBForeColor on a non-Color QuickDraw machine, ° d ONLN d
? K (g 6-$AA14 is treated as $A814, which is the trap ° d ONLN d
¨?K⁄ )È*word for SetFractEnable. SetFractEnable is ° d ONLN d
◊K Wæ (s 6Simplemented on 128K ROM machines or greater, so no unimplemented trap error occurs. ° d ONLN d +c o _ *If you look at ° d ONLN d :c _o⁄ )GKrecent DTS sample programs, such as the Utilities sample (SC.025.Utilities, ° d ONLN d Üo { ä (ó 6which you can find on ° d ONLN d úo ä{⁄ )r@AppleLink in Developer Support and on the current developer CD), ° d ONLN d ›{ á ◊ (£ 6+you’ll see a routine in Utilities.c called ° d ONLN d { ◊á⁄ )ø6TrapExists. It takes into account the size of the trap ° d ONLN d ?á ìI (Ø 6Edispatch table so that you can tell in one call whether a routine is ° d ONLN d ÑáIì⁄ (Øg implemented or not regardless ° d ONLN d ¢ì üÜ (ª 6Mof whether it’s a Color QuickDraw trap or not and regardless of what kind of ° d ONLN d ÔìÜü⁄ (ª§Macintosh you’re ° d ONLN d
) Å 5˛ )ELsoftware version 7.0, the trap dispatcher is modified on non-Color QuickDraw ° d ONLN d Z 5 < A ™ ( ] Zmachines so that many ° d ONLN d p 5 ™ A˛ )nBColor QuickDraw traps are implemented and work as well as they can ° d ONLN d ≥ A < M ñ ( i Zin black and white.
° d ONLN d « e < tz *'-Macintosh OpenCPicture 72-dpi calculation bug
∞q º˛ ( ÿèthe PicHandle returned by ° d ONLN d' º < » à ( ‰ Z_OpenCPicture. ° d ONLN d6 » < ‘ N * ___ ° d ONLN d: ‡ < Ï § *It’s a known bug that ° d ONLN dP ‡ § Ï˛ )hDunder Macintosh system software versions 6.0.5 and 6.0.7 with 32-Bit ° d ONLN dï Ï < ¯fl ( ZSQuickDraw 1.2, OpenCPicture doesn’t properly calculate the right coordinate of the ° d ONLN dË Ïfl ¯˛ (˝72-dpi ° d ONLN dÔ ¯ < l ( Z picFrame ° d ONLN d¯ ¯ l˛ )0Sif the height of the srcRect (native resolution rectangle) multiplied by 72 exceeds ° d ONLN dL <. (, Z.$0000FFFF. That works out to a maximum height ° d ONLN dz.˛ )Ú*of 910 pixels, just as you found. This bug ° d ONLN d• < J (8 Zis ° d ONLN d® J ˛ )Pfixed in System 7.0, but gestaltQuickdrawVersion returns $0220 both under system ° d ONLN d˘ <( € (D Z!software versions 6.0.5 and 7.0, ° d ONLN d €(˛ )ü=so you can’t tell whether the bug is fixed that way. Instead, ° d ONLN dX( <4 t (P Z you should ° d ONLN dc( t4˛ )8Ruse Gestalt with the gestaltSystemVersion selector. If the returned value is $0700 ° d ONLN d∂4 <@t (\ ZCor greater, then let OpenCPicture handle the picFrame calculation; ° d ONLN d˘4t@˛ (\íotherwise you should do the ° d ONLN d@ <L ú (h Zcalculation yourself.
° d ONLN d+d <sH *'"GetGWorldPixMap bug and workaround
° d ONLN dNs < b * Written: ° d ONLN dWs à ¨ )L3/12/91 ° d ONLN d_ <ã Å (ß ZLast reviewed: ° d ONLN dn àã ¨ )L10/9/91 ° d ONLN dvó <£ (ø Z&Why does GetGWorldPixMap (when called ° d ONLN dúó£˛ )◊.on a Macintosh II, IIcx, or IIx running system ° d ONLN dÀ£ <؇ (À ZWsoftware version 6.0.5 or 6.0.7 with 32-Bit QuickDraw 1.2) return a combination of the ° d ONLN d"£‡Ø˛ (À˛device ° d ONLN d)Ø <ªÆ (◊ ZQfield (two bytes) and the first two bytes of the portPixMap field? Is this a bug? ° d ONLN d{ª <« N * ___ ° d ONLN d” <fl ì *Your analysis of ° d ONLN dê” ìfl˛ )WEGetGWorldPixMap is exactly right: It doesn’t work correctly in system ° d ONLN d÷fl <Îs ( Z=software versions 6.0.5 and 6.0.7 with 32-Bit QuickDraw 1.2. ° d ONLN dflsβ (ë It returns a value that’s two ° d ONLN d1Î <˜ ( Z/bytes before the value it’s supposed to return. ° d ONLN da < Ö *The solution is ° d ONLN dq Ö˛ )IHto use GWorldPtr->portPixMap instead of GetGWorldPixMap. It’s safe to do ° d ONLN d∫ </ (7 Z/this, but you should use GetGWorldPixMap under ° d ONLN dÈ/˛ )Û*System 7. Not only is the bug fixed there, ° d ONLN d <'D (C Z7but dereferencing the port is dangerous under System 7 ° d ONLN dKD'˛ (Cb$because it may not be CGrafPort. Use ° d ONLN dp' <3T (O Z5Gestalt with the gestaltQuickdrawVersion selector to ° d ONLN d•'T3˛ (Or determine whether you can use ° d ONLN d√3 <? ([ Z&GetGWorldPixMap. If Gestalt returns a ° d ONLN dÈ3?˛ )›(value from gestalt8BitQD ($0100) through ° d ONLN d ? <KC (g Z/gestalt32BitQD12 ($0220), then GetGWorldPixMap ° d ONLN d A?CK˛ (ga$either doesn’t exist or is the buggy ° d ONLN d fK <W z (s Zversion. If it ° d ONLN d uK zW˛ )>Kreturns gestalt32BitQD13 ($0230) or higher, then GetGWorldPixMap does exist ° d ONLN d ¡W <cM ( Z4and works correctly. Interestingly, GetGWorldPixMap ° d ONLN d ıWMc˛ (k"can be called on a black-and-white ° d ONLN d
c <o\ (ã Z;QuickDraw machine under System 7. It returns a handle to a ° d ONLN d
Sc\o˛ (ãz#structure that should be treated as ° d ONLN d
wo <{ ª (ó Za bitmap structure, though ° d ONLN d
ío ª{˛ )Bthere are some undocumented fields after the normal bitmap fields. ° d ONLN d
’{ <áÉ (£ ZBTo tell whether GetGWorldPixMap is available on a black-and-white ° d ONLN d {ÉᲠ(£°QuickDraw machine, you ° d ONLN d .á <ì x (Ø Z must check ° d ONLN d 9á xì˛ )<Lthe system software version by calling Gestalt with the gestaltSystemVersion ° d ONLN d Üì <üä (ª ZFselector. If it returns $0700 or higher, GetGWorldPixMap is available. ◊ X◊
° d ONLN d& ˚ > * Written: ° d ONLN d/ ˚ d à )L6/19/91 ° d ONLN d7 ] (/ 6Last reviewed: ° d ONLN dF d é )L10/15/91 ° d ONLN dO +0 (G 6:When setting up a dithered grayscale image for subsequent ° d ONLN dâ 0+⁄ (GN$animation (to adjust brightness, for ° d ONLN dÆ+ 7 J (S 6
example), ° d ONLN d∏+ J7⁄ )2Ra conflict arises between the use of Palette animation and the ditherCopy CopyBits ° d ONLN d 7 C ~ (_ 6mode. This problem ° d ONLN d 7 ~C )fis demonstrated in the ° d ONLN d57 C )rdevelop ° d ONLN d<7C⁄ )%% #5 GiMeDaPalette code sample: If you ° d ONLN dbC O ∑ (k 6 change srcCopy to ditherCopy in ° d ONLN dÇC ∑O⁄ )ü;the CopyBits call, then run the program and select Animate, ° d ONLN dæO [ (w 6the resulting image is ° d ONLN d’O [⁄ )gGpure black and white, with what appears to be an attempt to dither with ° d ONLN d [ gè (É 6Sjust the black-and-white color table entries (that are not reserved for animation). ° d ONLN dqs *1This happens because ditherCopy tries to use the ° d ONLN d¢s⁄ )È,inverse table to do color matching, but when ° d ONLN dœ ãï (ß 6Tthe image is animated, the inverse table colors are limited to just black and white. ° d ONLN d$ó £ ( *To ° d ONLN d'ó (£⁄ )Twork around the problem, you can jump into the bottlenecks and when you see the PICT ° d ONLN d|£ Ø Ä (À 6hitting the opcode for ° d ONLN dì£ ÄØ⁄ )hBCopyBits, change the PICT from a srcCopy to a ditherCopy. This way ° d ONLN d÷Ø ª ° (◊ 6the dithering happens when ° d ONLN dÒØ °ª⁄ )â>you do the call to DrawPicture and not later on. This makes it ° d ONLN d0ª «. („ 6:possible to use dithering and animation on the same image.
° d ONLN dkfl Óó *'6Rendering color PICTs in a black-and-white environment
° d ONLN d¢Ó ˙ > * Written: ° d ONLN d´Ó d˙ à )L7/22/91 ° d ONLN d≥˙ ] (" 6Last reviewed: ° d ONLN d¬˙ d à )L9/17/91 ° d ONLN d ¢ (: 6QI want to be able to render a color PICT as a black-and-white image substituting ° d ONLN d¢ ⁄ (:¿ patterns for ° d ONLN d( *S (F 6Bcolors. My images are pretty small and have fewer than 16 colors. ° d ONLN dj S*⁄ (FqWhat do you suggest as the ° d ONLN dÖ* 6 S (R 6 easiest way? ° d ONLN dí6 B * * ___ ° d ONLN dñN Z Í *,One easy way is to take advantage of 32-Bit ° d ONLN d¬N ÍZ⁄ )“.QuickDraw and System 7.0’s ditherCopy transfer ° d ONLN dÒZ f ‡ (Ç 6%mode modifier or flag (documented in ° d ONLN d Z ‡f5 )»Inside Macintosh ° d ONLN d &Z5f⁄ )U Volume VI, page 17-17). Call ° d ONLN d Df rü (é 6QDrawPicture into an off-screen pixmap with the pixel depth of the original color ° d ONLN d ïfür⁄ (éΩ
PICT. Then ° d ONLN d †r ~ ó (ö 6call CopyBits to copy the ° d ONLN d ∫r ó~⁄ )?pixmap to the screen, with srcCopy + ditherCopy as the transfer ° d ONLN d ˙~ äÇ (¶ 6Mmode. This will result in a nicely dithered image on the black-and-white end. ◊ 4◊˘
*F10 )
of 31 (ÏîColor QuickDraw Q&As ˇ§ ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +Z-Developer Support Center ( -fi
December 1992 / X /
° d ONLN d < )¥ ( E ZKUnder System 6 without 32-Bit QuickDraw, the solution is not nearly so cut ° d ONLN d K ¥ )˛ ( E“and dried. One ° d ONLN d Z ) < 5m ( Q Z<way might be to take advantage of the fact that DrawPicture ° d ONLN d ñ )m 5˛ ( Qãgoes through the QuickDraw ° d ONLN d ± 5 < A È ( ] Z"bottlenecks for drawing. For each ° d ONLN d ” 5 È A˛ )≠5grafproc in your PICT, you’d intercept StdBits during ° d ONLN d A < Mfi ( i ZTDrawPicture and call your own dithering routine to examine the foreground color and ° d ONLN d] Afi M˛ ( i¸set the ° d ONLN de M < Y» ( u ZZpen pattern or fill pattern so that it has about the same lightness as the original color. ° d ONLN d¿ e < qü *LWell, this came out as a great sales pitch for writing a System 7-savvy app!
° d ONLN d
â < òÿ *';Highlighting ignored if foreground same as background color
° d ONLN dI ò < § b * Written: ° d ONLN dR ò à § ¶ )L8/7/91 ° d ONLN dY § < ∞ Å ( à ZLast reviewed: ° d ONLN dh § à ∞ ¨ )L9/24/91 ° d ONLN dp º < »f ( ‰ Z>Under System 7, but not System 6, HiliteColor is not used for ° d ONLN dÆ ºf »˛ ( ‰Ñ!InvertRect when the hilite bit is ° d ONLN d– » < ‘b ( Z7set and the background is exactly black (R=G=B=$0000). ° d ONLN d »b ‘˛ ( Ä Also, HiliteColor doesn’t draw ° d ONLN d& ‘ < ‡, ( ¸ Z0when a pen mode of XOR is used in a LineTo call. ° d ONLN dW ‡ < Ï N * ___ ° d ONLN d[ ¯ < R *The ° d ONLN d_ ¯ R˛ )Rproblem you encounter exists whenever the background and foreground colors are the ° d ONLN d≤ <j (, Z?same when using highlight mode. If the foreground color is the ° d ONLN dÒj˛ (,à same as the background color, ° d ONLN d < ï (8 ZIhighlighting is ignored. Therefore, when you set the foreground color to ° d ONLN dXï ˛ (8≥white, you should set ° d ONLN dn <(è (D ZHthe background color to something other than the default color of white.
° d ONLN d∑@ <Ob *'*Gestalt 'qdrw' selector bug and workaround
° d ONLN d‚O <[ b * Written: ° d ONLN dÎO à[ ¶ )L8/1/91 ° d ONLN dÚ[ <g Å (É ZLast reviewed: ° d ONLN d[ àg ¨ )L10/9/91 ° d ONLN d s <Ñ (õ Z<Why does Gestalt tell me I have Color QuickDraw features on ° d ONLN dEsÑ˛ (õ¢a non-Color QuickDraw ° d ONLN d[ <ã h (ß Zmachine? ° d ONLN ddã <ó N * ___ ° d ONLN dh£ <Ø≥ *JThe gestaltQuickdrawFeatures ('qdrw') selector, used for determining your ° d ONLN d≤£≥Ø˛ (À—system’s Color ° d ONLN d¡Ø <ª∏ (◊ ZSQuickDraw features, has a bug that causes it to tell you incorrectly that noncolor ° d ONLN dØ∏ª˛ (◊÷
machines have ° d ONLN d"ª <« [ („ Zcolor. ° d ONLN d)ª [«˛ ) XThe fix is quite simple: Gestalt has another selector, gestaltQuickdrawVersion ('qd '), ° d ONLN dÇ« <”V (Ô Z8which simply returns the QuickDraw version number. This ° d ONLN d∫«V”˛ (Ôt!version number is < gestalt8BitQD ° d ONLN d‹” <fl ƒ (˚ Zfor classic QuickDraw and ° d ONLN dˆ” ƒfl™ )à*>= gestalt8BitQD for Color QuickDraw (see ° d ONLN d ”™fl˛ )ÊInside Macintosh ° d ONLN d1fl <ε ( ZMVolume VI, page 3-39, for more information). The trick is to ask Gestalt for ° d ONLN d~flµÎ˛ (”
the QuickDraw ° d ONLN dåÎ <˜Õ ( ZPversion first; once you’ve determined that you have Color QuickDraw, the 'qdrw' ° d ONLN d‹ÎÕ˜˛ (Î selector is ° d ONLN d˘ < – ( Z OK to use to find out specifics. ◊ X◊
*ÕColor QuickDraw Q&As (Ï˙11 )
of 31 ˇl ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘
° d ONLN d ) 8f *'-Version 2 PICTs on pre-Color QuickDraw models
° d ONLN d . 8 D > * Written: ° d ONLN d 7 8 d D à )L8/13/91 ° d ONLN d ? D P ] ( l 6Last reviewed: ° d ONLN d N D d P é )L10/22/91 ° d ONLN d W \ h i ( Ñ 6Inside Macintosh ° d ONLN d g \ i h ∑ )Q Volume V says ° d ONLN d v \ ∑ h⁄ )N;a System 4.1 (and later) patch ensures that version 2 PICTs ° d ONLN d ≤ h t# ( ê 67are displayed correctly on earlier machines that don’t ° d ONLN d È h# t⁄ ( êA!have Color QuickDraw, such as the ° d ONLN d t Ä ( ú 6-Macintosh Plus and SE. However, my version 2 ° d ONLN d8 t Ä⁄ )˘&PICT, consisting primarily of a pixmap ° d ONLN d_ Ä åa ( ® 6C(opcode = $90 since rowBytes <8) displays correctly on a Macintosh ° d ONLN d¢ Äa å⁄ ( ®IIfx but displays garbage ° d ONLN dº å ò u ( ¥ 6on a Macintosh SE. ° d ONLN dœ ò § * * ___ ° d ONLN d” ∞ º *+The PICT problem you reported is caused by ° d ONLN d˛ ∞ º⁄ )ÿ,a bug in 6.0.7 QuickDraw. The workaround for ° d ONLN d+ º » t ( ‰ 6the time being is to: ° d ONLN dA ‘ ‡ Ê *+• Use System 7.0, where it’s been fixed, or ° d ONLN dm ‡ ÏO * @• Don’t use opcode $90. Instead, use padding so that opcode $98 ° d ONLN d≠ ‡O Ï⁄ (mcan be used. (Opcode $98 is ° d ONLN d… Ï ¯ ( 64the packed CopyBits version that works for rowBytes ° d ONLN d˝ Ï ¯⁄ (8'>= 8.). You can do this by creating the ° d ONLN d% ¯ Å ( 6picture with a pixmap ° d ONLN d; ¯ Å⁄ )iIthat’s wider than you actually need, and then use the clip region to clip ° d ONLN dÖ õ (, 6 out the part you don’t need.
° d ONLN d¢( 7 Û *' GetPixelsState is slow sometimes
° d ONLN d√7 C > * Written: ° d ONLN dÃ7 dC à )L8/27/91 ° d ONLN d‘C O ] (k 6Last reviewed: ° d ONLN d„C dO à )L9/24/91 ° d ONLN dÎ[ g¿ (É 6JWhy do I sometimes see incredible slowdowns under System 7.0 when calling ° d ONLN d5[¿g⁄ (Éfieither ° d ONLN d<g s3 (è 66GetPixelsState or LockPixels (I’m not sure which) for ° d ONLN drg3s⁄ (èQ the PixMapHandle of a GWorld ° d ONLN dès Ø (õ 6 allocated in temporary memory? ° d ONLN dÆ ã * * ___ ° d ONLN d≤ó £ ⁄ *)GetPixelsState takes an arbitrary amount ° d ONLN d€ó ⁄£⁄ )¬5of time since it makes a call to RecoverHandle to get ° d ONLN d£ Ø (À 6\the handle pointing to the baseaddr. Therefore, the slowdown you see as actually due to the ° d ONLN dm£ Ø⁄ (ÀËcall ° d ONLN drØ ªÖ (◊ 6Jto RecoverHandle, which is slow because it must traverse the heap to find ° d ONLN dºØÖª⁄ (◊£the pointer to the ° d ONLN dœª «x („ 6Ibaseaddr. LockPixels is not responsible for the slowdown because it does ° d ONLN dªx«⁄ („ñnot make call to any ° d ONLN d-« ” ˇ (Ô 61traps that could take an extended amount of time.
° d ONLN d_Î ˙6 *'(OpenCPicture and PICTs other than 72 dpi
° d ONLN dà˙ > * Written: ° d ONLN dë˙ d à )L10/2/91 ° d ONLN dô ] (. 6Last reviewed: ° d ONLN d® d à )L10/8/91 ° d ONLN d∞ *Œ (F 6\Can I use OpenCPicture to create PICTs with a higher resolution than 72 dots per inch (dpi)? ° d ONLN d
* 6 $ * __ ° d ONLN dB NJ *=There’s good news and bad news: The good news is that you’re ° d ONLN dMBJN⁄ (jh on top of the situation, which ° d ONLN dlN Z% (v 6:means the bad news is that there aren’t better ways to do ° d ONLN d¶N%Z⁄ (vC#what you want to do, mostly. Here’s ° d ONLN d Z f H (Ç 6
the scoop: ° d ONLN d’r ~ *2You can use vRes and hRes in pictures opened with ° d ONLN dr~⁄ )¯)OpenCPicture to tell QuickDraw it’s not a ° d ONLN d1~ ä— (¶ 6Z72-dpi picture, and as long as the application that receives the picture uses DrawPicture ° d ONLN dã~—ä⁄ (¶Ôto ° d ONLN déä ñw (≤ 6Eimage it, QuickDraw will Do The Right Thing—scaling it on the screen ° d ONLN d”äwñ⁄ (≤ïto 72 dpi instead of ° d ONLN dËñ ¢’ (æ 6[making it humongously large. Unfortunately, this way you lose hairlines; if you print such ° d ONLN d Cñ’¢⁄ (æÛa ◊ 4◊˘
(Ï 612 )
of 31 (ÏîColor QuickDraw Q&As ˇ ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +Z-Developer Support Center ( -fi
December 1992 / X /
° d ONLN d < ) Ë ( E Z'picture to a 72-dpi grafPort (like the ° d ONLN d ' Ë )˛ )¨:LaserWriter driver normally returns), you’ll get 1/72-inch ° d ONLN d b ) < 5? ( Q Z7lines instead of 1/300-inch lines as you probably want. ° d ONLN d ö A < M X *(This ° d ONLN d † A X M h ) can ° d ONLN d £ A h M ⁄ ) work correctly, but the ° d ONLN d º A ⁄ M˛ )r?receiving application has to notice that your picture is bigger ° d ONLN d ¸ M < Y S ( u Zthan ° d ONLN d M S Y˛ )Y72 dpi and ask PrGeneral to increase the resolution of the printing grafPort accordingly, ° d ONLN d[ Y < e ( Å Z)and this doesn’t always or often happen.)
° d ONLN dÖ } < åu *'+No System 7 QuickDraw alpha channel support
the unused ° d ONLN ddX <d ∏ (Ä Zbyte, which in your case ° d ONLN d}X ∏d˛ )|Bis the alpha channel. In fact, even CopyBits may alter the byte if ° d ONLN d¿d <p: (å Z7stretching or dithering is involved in the CopyBits by ° d ONLN d˜d:p˛ )˛)setting them to zero. Therefore, the only ° d ONLN d!p <|ó (ò ZIpossible workarounds for this problem are to not use the unused byte for ° d ONLN djpó|˛ (òµalpha channel storage ° d ONLN dÄ| <àL (§ Z=since the integrity of the data cannot be guaranteed; or, to ° d ONLN dΩ|Là˛ (§j"not use QuickDraw drawing routines ° d ONLN d‡à <î ‘ (∞ Z which can alter the unused byte.
° d ONLN d¨ <ª[ *'$BitsToRgn and MPW BitMapToRegionGlue
° d ONLN d&ª <« b * Written: ° d ONLN d/ª à« ≤ )L10/29/91 ° d ONLN d8« <” Å (Ô ZLast reviewed: ° d ONLN dG« à” ≤ )L12/11/91 ° d ONLN dPfl <Î
( Z%Which version of the system software ° d ONLN dufl
β )Œ.first contained the call BitsToRgn? Is there a ° d ONLN d§Î <˜µ ( ZPworkaround for this call if my users have an earlier version of system software? ° d ONLN dı˜ < N * ___ ° d ONLN d˘ < « *The call BitmapToRegion ° d ONLN d «˛ )ã5was introduced with 32-Bit QuickDraw and became fully ° d ONLN dG <' “ (C Zdocumented in Volume VI of ° d ONLN db “') )ñInside Macintosh, ° d ONLN ds)'] )W
which is ° d ONLN d}]'˛ )4 primarily System 7 information. ° d ONLN dù' <3 p (O Z However, ° d ONLN d¶' p3˛ )4Ksince the differences between System 7’s QuickDraw and 32-Bit QuickDraw are ° d ONLN dÚ3 <? » ([ Zminor, most of System 7’s ° d ONLN d 3 »?˛ )å<QuickDraw routines are available in system software prior to ° d ONLN d I? <K (g Z+System 7.0 using the 32-bit QuickDraw INIT. ° d ONLN d uW <c j * To check ° d ONLN d ~W jc˛ ).Rto see if a system contains 32-bit QuickDraw, you can use the following snippet of ° d ONLN d —c <o U (ã Zcode: ,
Courier
° d ONLN d ◊{ <Üï *E /* Find out if GWorlds and CQD are implemented on this machine */ ° d ONLN d
Ö <êr *
> (void) Gestalt (gestaltQuickdrawVersion, /*<*/&qdVersion); ° d ONLN d
\è <ö; *
3 gHasGWorlds = (qdVersion > gestaltOriginalQD && ° d ONLN d
ëô <§ *
- qdVersion < gestalt8BitQD) ° d ONLN d
ø£ <Æ1 *
1 || qdVersion >= gestalt32BitQD; ◊ X◊
*"Color QuickDraw Q&As (Ï˙13 )
of 31 ˇ@ ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘
° d ONLN d ) 5ü *$OIf you are using MPW as a development platform, MPW has a library call you can ° d ONLN d O )ü 5⁄ ( QΩ
even rowBytes ° d ONLN d∑ » ‘ ( 62(using ResEdit)? I want to avoid duplicating icon ° d ONLN dÈ » ‘⁄ )Í(bitmaps—one for color systems set to B&W ° d ONLN d ‘ ‡ , ( ¸ 6and ° d ONLN d ‘ , ‡⁄ )Qone for B&W systems—to reduce program size as well as development and maintenance ° d ONLN dh ‡ Ï´ ( 6Ycosts. The bitmaps in the 'cicn' can also be sized specifically to the task, whereas the ° d ONLN d¡ ‡´ Ï⁄ (…old B&W ° d ONLN d… Ï ¯ ê ( 6icons are of a fixed size ° d ONLN d„ Ï ê ¯⁄ )xBand contain no sizing information. It’s simple enough to read in a ° d ONLN d& ¯ ≈ ( 6#'cicn' and extract the bitmap. The ° d ONLN dI ¯ ≈⁄ )≠3problem is that on a 68000 (no Color QuickDraw), if ° d ONLN d} Ô (, 6-rowBytes is odd, an odd address trap results. ° d ONLN d´ * * ___ ° d ONLN dØ( 4* *<There isn’t any way to get ResEdit itself to create bitmaps ° d ONLN dÎ(*4⁄ (PH#with even rowBytes for 8 x 8 'cicn' ° d ONLN d4 @ ÷ (\ 6(resources, but here are few suggestions: ° d ONLN d8L X å *You could process your ° d ONLN dOL åX⁄ )tF'cicn' resources first, so that they have bitmaps as you require them. ° d ONLN dñX dµ (Ä 6UTo alter the resource with a quick little program would be trivial, especially given ° d ONLN dÎXµd⁄ (Ä”that the ° d ONLN dÙd p Ô (å 6/bitmap data sits last in the 'cicn'. All you’d ° d ONLN d#d Ôp⁄ )◊-need to do is expand the bitmap image data by ° d ONLN dQp |ü (ò 6Qpadding each line to an even length and then changing the rowBytes value. Or you ° d ONLN d¢pü|⁄ (òΩ could de-rez ° d ONLN dØ| à (§ 66the 'cicn's and patch them with a text editor, either ° d ONLN dÂ| à⁄ )Ò+by hand or with a search-and-replace script ° d ONLN dà î Z (∞ 6
of some kind.
° d ONLN d ¨ ª∏ *';CopyBits blend mode: OpColor’s affect & eliminating banding
:W cõ ( 6Qdescribes the proportions to mix the source and destination colors in the blend. ° d ONLN d
ãWõc⁄ (π For an equal ° d ONLN d
òc o l (ã 6mix, you should ° d ONLN d
®c lo⁄ )TIset this color to a halfway gray. (Call OpColor() with a color where red, ° d ONLN d
Úo { ∑ (ó 6"green, and blue all equal $8000.) ° d ONLN d o ∑{⁄ )ü=This effect is described in the description of the blend mode ° d ONLN d R{ á ( (£ 6on ° d ONLN d U{ (á c ) page 60 of ° d ONLN d `{ cá ∂ );Inside Macintosh ° d ONLN d p{ ∂á⁄ )S: Volume V. Unfortunately, the initial value for OpColor is ° d ONLN d ´á ì^ (Ø 6Dblack (0,0,0), so you were seeing no mixing of your off-screen data. ◊ 4◊˘
5Ω A˛ ( ]€inverse table, ° d ONLN d A < M∞ ( i ZNyou’ll find that you’ll get only 2^4 = 16 levels of gray. If you enlarge your ° d ONLN dg A∞ M˛ ( iŒscreen’s inverse ° d ONLN dx M < YU ( u Z>table to 5 bits, the maximum allowable, you’ll still only get ° d ONLN d∂ MU Y˛ ( us$32 gray levels. (To do this, set the ° d ONLN d€ Y < e ◊ ( Å Z gdResPref field in the GDevice ° d ONLN d˙ Y ◊ e˙ )õ:to 5, then call MakeITable().) The only way to get a fully ° d ONLN d4 Y˙ e˛ ( Å- ° d ONLN d5 e < q ‹ ( ç Z$gradual, great-looking effect is to ° d ONLN dY e ‹ q˛ )†;do all the work off-screen in 24-bit deep pixmaps, and then ° d ONLN dï q < } _ ( ô Zcopy it ° d ONLN dù q _ }˛ )#Vto the screen. Because they can operate directly on colors, rather than having to work ° d ONLN dÙ } < âÒ ( • Z\through the intermediary of color indices, direct pixmaps are not limited by inverse tables ° d ONLN dP }Ò â˛ ( •(in ° d ONLN dT â < ïj ( ± Z?fact, they don’t even have real inverse tables). You could use ° d ONLN dì âj ï˛ ( ±à 16-bit pixmaps, but they only ° d ONLN d± ï < ° ¸ ( Ω Z)provide 32 grays (having only 5 bits for ° d ONLN d⁄ ï ¸ °˛ )¿4each component), so this wouldn’t be any better than ° d ONLN d ° < ≠ Ú ( … Z)increasing the size of the inverse table.
° d ONLN d9 ≈ < ‘_ *'(Icon dimming under System 7 and System 6
° d ONLN d™¨ <ª‘ *'8QuickDraw out of memory if debugger invoked by “Jackson”
° d ONLN d„ª <« b * Written: ° d ONLN dϪ à« ¨ )L3/11/92 ° d ONLN dÙ« <” Å (Ô ZLast reviewed: ° d ONLN d« à” ¶ )L4/7/92 ° d ONLN d
fl <Î Ã ( Z I am getting a strange bug in ° d ONLN d(fl Ãβ )ê:which the Macintosh debugger is being invoked by an A-trap ° d ONLN dcÎ <˜Å ( ZDmarked “Jackson” when I call SetCCursor in certain situations and a ° d ONLN dßÎز (üsecond monitor is hooked ° d ONLN d¿˜ <¿ ( ZSup. The cursor structure being passed appears to be valid. I’ve also been crashing ° d ONLN d ˜¿˛ ( fi unexpectedly ° d ONLN d <} (+ ZCin this same spot for the past few weeks. I assume Jackson is some ° d ONLN d c}˛ (+õ kind of error assertion that ° d ONLN d Ä <V (7 Z8was left in System 7’s Color QuickDraw code. What gives? ° d ONLN d π <' N * ___ ° d ONLN d Ω3 <? ú *Jackson was a code ° d ONLN d –3 ú?˛ )`Iname for 32-Bit QuickDraw. The trap you refer to is in fact never called; ° d ONLN d
? <K¡ (g ZSit’s not supposed to be encountered by you ever. The trap is reserved for Apple to ° d ONLN d
m?¡K˛ (gfl
use in future ° d ONLN d
{K <W (s Z,versions of Color QuickDraw. If you examine ° d ONLN d
ßKW˛ )›.the code directly preceding the _Debugger, you ° d ONLN d
÷W <c ≥ ( Z will notice that it is doing ,
Courier
° d ONLN d
Ûo <z æ * MOVEQ #$19,D0 ° d ONLN d y <Ñ » *
JSR ([$1524])
° d ONLN d +è <õ Ø *which for you and me is ◊ X◊
*5Color QuickDraw Q&As (Ï˙15 )
of 31 ˇ
‚ ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘ ,
Courier
° d ONLN d (S *? MoveQ #25,D0 ; say that memory is full… ° d ONLN d @ ' 20 *
8 _SysError ; and call syserror
° d ONLN d y = I ¶ * the line following would be...
° d ONLN d ò U `ä *J _Debugger ; Hey! sysError came back! Better drop into the debugger
° d ONLN d „ k w ¬ *%What’s all this tell you? You have a ° d ONLN d k ¬ w⁄ )™;debugger installed that is rts’ing from the SysError vector ° d ONLN dD w É ( ü 6-(you aren’t supposed to return from SysError ° d ONLN dq w É⁄ )Ë)normally), or you have installed your own ° d ONLN dõ É èq ( ´ 6GSysError vector which is rts’ing. At any rate, if you examine the code ° d ONLN d‚ Éq è⁄ ( ´èdirectly following the ° d ONLN d˘ è õ ∂ ( ∑ 6 debugger statement and see what ° d ONLN d è ∂ õ⁄ )û:it does, you might imagine the source code looks something ° d ONLN dT õ ß @ ( √ 6
like this:
° d ONLN d_ ≥ æl *DMemFull MoveQ #25,D0 ; say that memory is full... ° d ONLN d§ Ω »? *
; _SysError ; and call syserror ° d ONLN d‡ « “î *
L; If it returns better go into the debugger since its not supposed to return ° d ONLN d- — ‹b *
B _Debugger ; Hey! sysError came back! ° d ONLN dp € Ê *
; ° d ONLN dr  ê *
CallNewHand _NewHandle ° d ONLN dã Ô ˙î *
L bne.S MemFull ; could not get the memory, just die ° d ONLN dÿ ˘ m *
rts
° d ONLN dÍ w *What’s happening ° d ONLN d˚ w⁄ )_Ais that you’re running out of memory somehow (several places call ° d ONLN d= ' — (C 6'MemFull, not just the above place), so ° d ONLN dd —'⁄ )π5you’d need to use a stack crawl to figure out how you ° d ONLN dö' 3i (O 6Egot there. But, the bottom line, QuickDraw has run out of memory and ° d ONLN dfl'i3⁄ (Oácannot continue; it tried ° d ONLN d˘3 ? ([ 65to put up a system error dialog to tell the user and ° d ONLN d.3?⁄ )¯'for some reason the machine did not get ° d ONLN dV? K§ (g 6Prestarted and the SysError vector returned. You are now in your debugger, since ° d ONLN d¶?§K⁄ (g¬ QuickDraw ° d ONLN d∞K W4 (s 6=put up the system error dialog because it could not continue.
° d ONLN dÓo ~ú *'6ditherCopy not supported on LaserWriter or ImageWriter
° d ONLN d%~ ä > * Written: ° d ONLN d.~ dä à )L5/31/91 ° d ONLN d6ä ñ ] (≤ 6Last reviewed: ° d ONLN dEä dñ à )L11/6/91 ° d ONLN dM¢ Æ• ( 6OditherCopy is not supported on LaserWriters or ImageWriters. On a LaserWriter, ° d ONLN dú¢•Æ⁄ ( √
ditherCopy ° d ONLN dßÆ ∫ (÷ 61gets misinterpreted and inverts the image. On an ° d ONLN dÿÆ∫⁄ )Ó*ImageWriter it’s treated as a srcCopy. The ° d ONLN d∫ Δ√ (‚ 6TImageWriter driver doesn’t support color grafPorts, which is the only way to do the ° d ONLN dW∫√Δ⁄ (‚·pixel ° d ONLN d]Δ “d (Ó 6Eimage required for ditherCopy. Use srcCopy instead for both printers. ◊ 4◊˘
*˛16 )
of 31 (ÏîColor QuickDraw Q&As ˇ¯ ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +Z-Developer Support Center ( -fi
December 1992 / X /
° d ONLN d ) < 8Á ( T Z;Macintosh Color QuickDraw CalcCMask and SeedCFill clarified
° d ONLN d < 8 < D b * Written: ° d ONLN d E 8 à D ¶ )L1/1/90 ° d ONLN d L D < P Å ( l ZLast reviewed: ° d ONLN d [ D à P ≤ )L11/21/90 ° d ONLN d d \ < hÆ ( Ñ ZHI’m having trouble using CalcCMask and SeedCFill. What am I doing wrong? ° d ONLN d ≠ h < t N * ___ ° d ONLN d ± Ä < å, *-There is some confusion regarding the use of ° d ONLN d fi Ä, å˛ )&the Macintosh Color QuickDraw routines ° d ONLN d å < ò0 ( ¥ Z0CalcCMask and SeedCFill, which are analogous to ° d ONLN d5 å0 ò˛ )Ù(the older CalcMask and SeedFill. Much of ° d ONLN d^ ò < §L ( ¿ Z8the confusion was caused by early documentation errors. ° d ONLN dñ òL §˛ ( ¿j$Be sure you have the release version ° d ONLN dª § < ∞ á ( à Zof Volume 5 of ° d ONLN d § á ∞ ÿ )KInside Macintosh ° d ONLN d⁄ § ÿ ∞à )Q5 and version 2.0 or later of the MPW interface files. ° d ONLN d º < » ı ( ‰ Z'The correct interface for CalcCMask is: ,
Courier
° d ONLN d8 ‘ < fl *-PROCEDURE CalcCMask(srcBits, dstBits: BitMap; ° d ONLN df fi < È · *
° d ONLN dÏ < Ì *'The correct interface for SeedCFill is:
° d ONLN d* <5 *-PROCEDURE SeedCFill(srcBits, dstBits: BitMap; ° d ONLN dB4 <? · *
! srcRect, dstRect: Rect; ° d ONLN dd> <I Ê *
" seedH, seedV: INTEGER; ° d ONLN dáH <S » *
matchProc: Ptr; ° d ONLN d§R <] · *
! matchData: LongInt);
° d ONLN dΔh <t ˚ *'Each routine calculates a one-bit deep ° d ONLN dÌh ˚t˛ )ø4bitmap representing either the mask or the fill area ° d ONLN d"t <Ģ (ú ZWdepending upon the routine. In both cases, the source bitmap may be either a bitmap or ° d ONLN dyt˘Ä˛ (úa ° d ONLN d{Ä <å— (® ZVpixmap, but the destination must be a bitmap, because it must have a depth of one-bit. ° d ONLN d“ò <§ • *It is difficult to pass a ° d ONLN dÏò •§˛ )iEpixmap for the source parameter because of Pascal’s type checking. To ° d ONLN d2§ <∞9 (à Z7get around this difficulty, you can declare a new type:
° d ONLN djº <« æ * BitMapPtr = ^BitMap
° d ONLN dÖ“ <fi *,then use it to coerce the pixmap as follows:
° d ONLN d≤Í <ı *+ SeedCFill(BitMapPtr(@myPixMap)^, ...);
° d ONLN dfi < *-If you have a PixMapHandle, do the following:
° d ONLN d <#1 *1 SeedCFill(BitMapPtr(myPixMapHandle^)^, ...);
° d ONLN d>. <:G *8If you are using a grafPort (or a window), you can pass ° d ONLN dv.G:˛ (Ve"myWindow^.portBits and not have to ° d ONLN dô: <FH (b Z7worry about whether the port uses a bitmap or a pixmap. ° d ONLN d—R <^; *8Most of the other parameters are explained in detail in ° d ONLN d R;^ë )ˇInside Macintosh. ° d ONLN dRë^˛ )V To use the matchProc ° d ONLN d0^ <j{ (Ü Z@and the matchData parameters, though, you need more information. ° d ONLN dqv <Ç v *
As stated in ° d ONLN d~v vÇ À ):Inside Macintosh, ° d ONLN dèv ÀÇê )U+ the matchProc parameter is a pointer to a ° d ONLN d∫vêDz )≈routine that you would ° d ONLN d—Ç <é÷ (™ ZYlike to use as a custom SearchProc. To better understand how this is used, it is helpful ° d ONLN d*Ç÷é˛ (™Ùto know ° d ONLN d2é <ö (∂ Z*how SeedCFill and CalcCMask actually work. ◊ X◊
*6Color QuickDraw Q&As (Ï˙17 )
of 31 ˇÓ ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘
° d ONLN d )» *ZBoth routines start by creating a temporary bitmap which, by definition, is one bit deep. ° d ONLN d Z » )⁄ ( EÊThe ° d ONLN d ^ ) 5 q ( Q 6source pixmap (or ° d ONLN d p ) q 5⁄ )YHbitmap) is then copied to the temporary bitmap using CopyBits. This copy ° d ONLN d π 5 A ˝ ( ] 6/causes the image to be converted to a depth of ° d ONLN d Ë 5 ˝ A⁄ )Â*one-bit. Now with a normal black-and-white ° d ONLN d A M… ( i 6\image, the standard CalcMask or SeedFill routine is used to generate the destination bitmap. ° d ONLN dp Y eä *OMost of the real work is done in the original call to CopyBits, which maps the ° d ONLN dø Yä e⁄ ( Å®pixmap image to ° d ONLN dœ e q« ( ç 6Wa monochrome bitmap equivalent. For each color in the source pixmap, CopyBits will map ° d ONLN d& e« q⁄ ( çÂit to ° d ONLN d, q }M ( ô 6@either black or white. Which colors map to black and which ones ° d ONLN dl qM }⁄ ( ôk to white is determined by the ° d ONLN dä } â R ( • 6 SearchProc. ° d ONLN dñ ï ° *2SeedCFill installs a default SearchProc that maps ° d ONLN d» ï °⁄ )Í/all colors to black except for the color of the ° d ONLN d¯ ° ≠π ( … 6\pixel at (seedH,seedV). SeedFill then calculates as usual the fill mask for the white bits . ° d ONLN dU π ≈ **The default SearchProc for CalcCMask maps ° d ONLN d π ≈⁄ )ÿ2all colors to white except the color passed in the ° d ONLN d≤ ≈ —ô ( Ì 6JseedRGB parameter. The seedRGB parameter, then, would be the color of the ° d ONLN d¸ ≈ô —⁄ ( Ì∑
item that you ° d ONLN d
— › o ( ˘ 6wanted to “lasso.” ° d ONLN d È ıÆ *UBut suppose you want to fill over all colors that were shades of green, not just the ° d ONLN dr ÈÆ ı⁄ (Ã
particular ° d ONLN d} ı M ( 6@shade of green at (seedH,seedV). Or maybe you want to fill over ° d ONLN dΩ ıM⁄ ( k all colors that are lighter than ° d ONLN dfi
L () 6 50 percent ° d ONLN dÈ L
⁄ )4Nbrightness. Or maybe you want to use dark colors as edge colors for CalcCMask. ° d ONLN d8
I (5 6:To do such things, you need to pass a pointer to your own ° d ONLN dr
I⁄ (5gSearchProc in the matchProc ° d ONLN dé % J (A 6
parameter. ° d ONLN dô1 =Q *ABecause your matchProc is just a custom search procedure for the ° d ONLN d⁄1Q=⁄ (YoColor Manager, it should be ° d ONLN dˆ= I ‰ (e 6$declared as one, but Volumes I–V of ° d ONLN d= ‰I )ÃInside ° d ONLN d!=I9 )$ Macintosh ° d ONLN d*=9I⁄ )1 have documented this routine ° d ONLN dHI Uu (q 6Kincorrectly. The correct declaration for a custom SearchProc is as follows: ,
Courier
° d ONLN dîa l ÷ *&FUNCTION SearchProc(VAR RGB: RGBColor; ° d ONLN dªk v  *
) VAR result: LongInt) : Boolean;
° d ONLN dÂÅ ç ™ * Normally, as each SearchProc ° d ONLN dÅ ™ç⁄ )íAis installed, it is added to the head of the SearchProc chain, so ° d ONLN dDç ôó (µ 6Sthat it is called before all of the other ones that were already installed. When a ° d ONLN dóçóô⁄ (µµ
SearchProc is ° d ONLN d•ô • à (¡ 6)installed, it can do one of three things: ° d ONLN dœ± Ω6 *51. Completely ignore the call by returning FALSE and ° d ONLN d±6Ω⁄ (ŸT not modifying any of the input ° d ONLN d#Ω … N ( 6 parameters; ° d ONLN d/… ’4 * >2. Completely handle the call by setting the result parameter ° d ONLN dm…4’⁄ (ÒR$to be the index into the color table ° d ONLN dí’ ·< (˝ 6=that matches (according to your rules) the RGB parameter. In ° d ONLN dœ’<·⁄ (˝Z!that case, the SearchProc returns ° d ONLN dÒ· Ì : ( 6TRUE; ° d ONLN d˜Ì ˘ß * R3. Partially handle the call by modifying the RGB parameter, then returning FALSE. ° d ONLN d J á *HIn cases 1 and 3, the Color Manager continues down the SearchProc chain ° d ONLN d íá⁄ (-•until it finds one ° d ONLN d • R (9 6
that returns ° d ONLN d ≤ R ⁄ ):OTRUE. If none of the custom routines handle the call, then the built-in default ° d ONLN d
) · (E 6+routine is used. In case 3, you can change ° d ONLN d
- ·)⁄ )…1the RGB color that is being matched. For example, ° d ONLN d
_) 5æ (Q 6Qif you want all shades of green to map to pure green, modify the RGB color, then ° d ONLN d
∞)æ5⁄ (Q‹return ° d ONLN d
∑5 Aí (] 6QFALSE, letting the Color Manager find the index of that green in the color table. ° d ONLN d M YK *BIn case 2, you return TRUE to indicate that you handled the call, ° d ONLN d KMKY⁄ (ui and you return the color table ° d ONLN d jY e# (Å 66index in the result parameter. The Color Manager then ° d ONLN d †Y#e⁄ (ÅA$uses that index. For example, if you ° d ONLN d ≈e qT (ç 6Fwant to substitute white for all colors that can’t be matched exactly ° d ONLN d eTq⁄ (çr in the color table, then each ° d ONLN d )q } 0 (ô 6time ° d ONLN d .q 0}⁄ )Xyou get called you either return the index into the color table of the exact color, or 0 ° d ONLN d á} â (• 64(which is the index for white) for all other colors. ° d ONLN d ºï ° H * A custom ° d ONLN d ≈ï H°⁄ )0LSearchProc for SeedCFill and CalcCMask should always return TRUE because the ° d ONLN d
° ≠ > (… 6default ° d ONLN d
° >≠⁄ )&JColor Manager SearchProc usually doesn’t make sense. Because SeedCFill and ◊ 4◊˘
(Ï 618 )
of 31 (ÏîColor QuickDraw Q&As ˇ ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +Z-Developer Support Center ( -fi
December 1992 / X /
° d ONLN d < )ò ( E ZHCalcCMask are using CopyBits to copy to a 1-bit bitmap, you need to set ° d ONLN d H ò )˛ ( E∂the result to be either ° d ONLN d ` ) < 5 p ( Q Z 0 or 1 (the ° d ONLN d l ) p 5˛ )4Uonly possible values in a 1-bit bitmap). A result of 0 is white, and a result of 1 is ° d ONLN d ¬ 5 < A Y ( ] Zblack. ° d ONLN d … M < Y ∞ *All colors for SeedCFill ° d ONLN d ‚ M ∞ Y˛ )tFthat should be “filled over” would generate a result of 0 (white), and ° d ONLN d) Y < e ( Å Z4all colors that stop the fill generate a 1 (black). ° d ONLN d] Y e˛ )›3SeedFill is then called to fill the white area. All ° d ONLN dë e < qÒ ( ç Z[colors for CalcCMask that you want to form boundaries should generate results of 1 (black). ° d ONLN dÌ } < â[ */When your SearchProc gets called, the gdRefCon ° d ONLN d }[ Ⲡ( •y field of the current GDevice ° d ONLN d9 â < ïÑ ( ± ZC(theGDevice^^.gdRefCon) contains a pointer to the following record: ,
Courier
° d ONLN d} ° < ¨ Ø * matchRec = RECORD ° d ONLN dï ´ < ∂ π *
red: Integer; ° d ONLN dØ µ < ¿ π *
green: Integer; ° d ONLN d… ø < π *
blue: Integer; ° d ONLN d„ … < ‘ π *
matchData: LongInt; ° d ONLN d˝ ” < fi d *
END;
° d ONLN d È < ıà *DThe red, green, and blue parameters for SeedCFill are the values of ° d ONLN dJ Èà ı˛ (¶the color of the pixel at ° d ONLN dd ı <x ( Z;(seedH,seedV). For CalcCMask, they are the fields from the ° d ONLN dü ıx˛ ( ñseedRGB parameter. Your ° d ONLN d∑ <
() Z.SearchProc can use this information to decide ° d ONLN dÂ
˛ )·-which colors are “fill-over” colors and which ° d ONLN d
< À (5 Z colors are “boundary” colors. ° d ONLN d1
Z/next row (rowBytes). Although these parameters ° d ONLN d gÂ,Ò˛ ),are fairly easy to calculate, there are some ° d ONLN d îÒ <˝ q ( Z limitations. ° d ONLN d ° < À * The most restrictive limitation ° d ONLN d ¡ À˛ )è@is that the width of the rectangle used must be an even multiple ° d ONLN d
<!≥ (= ZPof 16 bits. This limitation exists because the width of the rectangle is passed ° d ONLN d
R≥!˛ (=—to SeedFill and ° d ONLN d
b! <- º (I ZCalcMask as a number of ° d ONLN d
z! º-˛ )Ä?words (2 bytes). When calculating this parameter, SeedCFill and ° d ONLN d
∫- <9œ (U ZLCalcCMask round down to an even word boundary. This rounding means that the ° d ONLN d -œ9˛ (UÌ
° d ONLN d ) H * You have ° d ONLN d H )⁄ )0Qtwo methods to make it work. First, always pass the pixmap of the current port as ° d ONLN d [ ) 5§ ( Q 6Othe source parameter. If you are using an off-screen pixmap, it is a good idea ° d ONLN d ™ )§ 5⁄ ( Q¬
to have an ° d ONLN d µ 5 A* ( ] 6<associated port for it, and then call SetPort, passing it a ° d ONLN d Ò 5* A⁄ ( ]H$pointer your off-screen port, before ° d ONLN d A M s ( i 6you call SeedCFill. ° d ONLN d* Y eú *FThe second method involves letting SeedCFill get some wrong value for ° d ONLN dp Yú e⁄ ( Å∫ the color at ° d ONLN d} e q3 ( ç 64(seedH,seedV) then using your own custom SearchProc ° d ONLN d± e3 q⁄ ( çQ to do the real work. The default ° d ONLN d“ q } ( ô 67SearchProc for SeedCFill relies on getting the correct ° d ONLN d q }⁄ )˛'color, but your SearchProc doesn’t have ° d ONLN d1 } â % ( • 6to. ° d ONLN d5 ï ° K *
SeedCFill ° d ONLN d? ï K °⁄ )3Nalso makes the assumption that the seedH and seedV parameters are in the local ° d ONLN dé ° ≠ ( … 62coordinate system of the destination bitmap. This ° d ONLN d¿ ° ≠⁄ )Î)assumption comes into play when SeedCFill ° d ONLN dÍ ≠ π ( ’ 67calculates the seedH and seedV parameters for SeedFill. ° d ONLN d" ≈ —≥ *UAll this means that SeedCFill only works correctly if the source pixmap, destination ° d ONLN dw ≈≥ —⁄ ( Ì—pixmap, ° d ONLN d — › x ( ˘ 6and current port all ° d ONLN dî — x ›⁄ )`Euse the same coordinate system. Because of the above problem, this is ° d ONLN d⁄ › Èm ( 6Ialmost automatic since the current port’s portRect and the bounds of the ° d ONLN d# ›m È⁄ (ãsource pixmap have to ° d ONLN d9 È ı { ( 6be the same anyway. ° d ONLN dM
‘ *&The easiest way to make all this work ° d ONLN ds ‘
⁄ )º3is to have your main port be an even multiple of 16 ° d ONLN dß
ß (5 6Qpixels wide. Then, make sure that your source and destination structures (pixmap ° d ONLN d¯
ß⁄ (5≈
or bitmap) ° d ONLN d % (A 64are all the same size and all have origins of (0,0).
° d ONLN d8= L *'#System 7.0ß1 BitMapToRgn limitation
° d ONLN d\L X > * Written: ° d ONLN deL dX Ç )L1/1/90 ° d ONLN dlX d ] (Ä 6Last reviewed: ° d ONLN d{X dd à )L12/7/90 ° d ONLN dÉp | ˝ (ò 6-BitMapToRegion does not work as described in ° d ONLN d∞p ˝|⁄ )Â*the Macintosh Tech Note “32-Bit QuickDraw: ° d ONLN d€| àG (§ 6:Version 1.2 Features” for a pixmap with baseAddr = (NuBus ° d ONLN d|Gà⁄ (§e address). Which calls support ° d ONLN d3à î (∞ 61pixmap 32-bit base addressing with pmVersion = 4? ° d ONLN de† ¨ * *___ ° d ONLN di∏ ƒj *=As of System 7.0ß1, BitMapToRgn cannot handle a bitmap whose ° d ONLN d¶∏jƒ⁄ (‡àbase address is in the ° d ONLN dΩƒ –! (Ï 67NuBus address space or any bitmap that requires 32-bit ° d ONLN dÙƒ!–⁄ (Ï?%addressing. The problem will be fixed ° d ONLN d– ‹ ) (¯ 6for ° d ONLN d – )‹⁄ )XSystem 7’s final release. BitMapToRgn seems to be the only call that doesn’t yet support ° d ONLN dw‹ Ë í ( 632-bit addressed bitmaps. ° d ONLN dëÙ 9 *X-Ref: ° d ONLN dò y * EDTS Macintosh Technical Note “32-Bit QuickDraw: Version 1.2 Features” ◊ 4◊˘
*ƒ20 )
of 31 (ÏîColor QuickDraw Q&As ˇ¸ ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +Z-Developer Support Center ( -fi
December 1992 / X /
° d ONLN d ) < 8v ( T Z*Macintosh Color QuickDraw and packed PICTs
° d ONLN d + 8 < D b * Written: ° d ONLN d 4 8 à D ¶ )L1/1/90 ° d ONLN d ; D < P Å ( l ZLast reviewed: ° d ONLN d J D à P ¨ )L12/7/90 ° d ONLN d R \ < h ( Ñ Z(Does Macintosh 32-Bit QuickDraw support ° d ONLN d z \ h˛ )’-packed PICTs? What’s the technique for saving ° d ONLN d ® h < tt ( ê Z<packed PICT formats? What compression schemes are supported? ° d ONLN d  t < Ä N * ___ ° d ONLN d È å < òb *7Color QuickDraw has always supported packed PICTs. See ° d ONLN d åb òÉ ( ¥ÄInside ° d ONLN d' åÉ ò¥ )! Macintosh ° d ONLN d0 å¥ ò˛ )1
Volume V for ° d ONLN d> ò < §Â ( ¿ ZOdetails on how CLUT pixmaps are packed. Under 32-Bit QuickDraw, to pack direct ° d ONLN dç ò §˛ ( ¿RGB ° d ONLN dë § < ∞ ( à Z[pixmaps in PICTs, call CopyBits with the packType field in the source pixmap set to one of ° d ONLN dÏ § ∞˛ ( Ãthe ° d ONLN d ∞ < º= ( ÿ Z5following constants that apply to direct RGB pixmaps: ° d ONLN d& » < ‘ä *E0—default packing (pixelSize 16 defaults to packType 3 and pixelSize ° d ONLN dk »ä ‘˛ ( ®32 defaults to packType ° d ONLN dÉ ‘ < ‡ F ( ¸ Z4) ° d ONLN dÜ ‡ < Ï Ç * 1—no packing ° d ONLN dì Ï < ¯ ˙ * &2—remove pad byte (32-bit pixels only) ° d ONLN d∫ ¯ <n * ?3—run-length encoding by pixel size chunks (16-bit pixels only) ° d ONLN d˙ <ë * G4—run-length encoding, all of one component at the time, one scan line ° d ONLN dAë˛ (,Øat a time (24-bit pixels ° d ONLN dZ < U (8 Zonly) ° d ONLN d`( <4w *DScheme 4 will store the alpha channel also if cmpCount is set to to ° d ONLN d§(w4˛ (Pï. PackSize is not used and ° d ONLN d¿4 <@ a (\ Zshould ° d ONLN d«4 a@˛ )%Pbe set to 0 for compatibility reasons. These are the only compression techniques ° d ONLN d@ <L • (h Zsupported at this time.
° d ONLN d0d <sQ *'(Macintosh PICT color picture file format
° d ONLN dYs < b * Written: ° d ONLN dbs à ¶ )L1/1/90 ° d ONLN di <ã Å (ß ZLast reviewed: ° d ONLN dx àã ≤ )L11/21/90 ° d ONLN dÅó <£ J (ø ZIs ° d ONLN dÑó J£˛ )Wthere a general file format for color pictures that is common to all of the color paint ° d ONLN d‹£ <Ø (À Z(programs? If so, where is it documented? ° d ONLN dØ <ª N * ___ ° d ONLN d « <”Å *DApple supports (and encourages developers to support) one file type ° d ONLN dM«Å”˛ (Ôüfor pictures: the PICT file ° d ONLN di” <fl+ (˚ Z1type. Most paint-type programs handle PICT files. ° d ONLN dõÎ <˜í *KA PICT file is composed of two parts in its data fork; the first 512 bytes ° d ONLN dÊÎí˜˛ (∞are for the file header, ° d ONLN dˇ˜ <| ( Z;which contains application-dependent information. You have ° d ONLN d:˜|˛ ( öto contact the individual ° d ONLN dT <\ (+ Z=publishers to find out their particular data structures. For ° d ONLN dë\˛ (+z example, you can contact Claris ° d ONLN d± < o (7 Z
Technical ° d ONLN dª o˛ )3FSupport at AppleLink CLARIS.TECH or (415) 962-0371 for the file header ° d ONLN d <' ø (C Z MacDraw writes to its files. ° d ONLN d 3 <?È *SThe rest of the data in the file is picture data as created by Macintosh QuickDraw ° d ONLN dr3È?˛ ([with ° d ONLN dw? <Ke (g Z=OpenPicture. You can find the information about this data in ° d ONLN d¥?eK´ (gÉ Volume V of ° d ONLN d¿?´K˛ )FInside Macintosh ° d ONLN d—K <Wá (s ZE(pages 84–105); this section also shows how to read/write PICT files. ° d ONLN dc <o f *You can ° d ONLN d c fo˛ )*Qalso check the Macintosh Tech Note “Displaying Large PICT Files” for more details ° d ONLN dqo <{ Å (ó Zon the subject. ◊ X◊
*UColor QuickDraw Q&As (Ï˙21 )
of 31 ˇ
ö ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘
° d ONLN d ) 5 > *$X-Refs: ° d ONLN d 5 Au * FDTS Macintosh Technical Note “QuickDraw’s Internal Picture Definition” ° d ONLN d O A MA * :DTS Macintosh Technical Note “Displaying Large PICT Files”
° d ONLN d ä e t∏ *'<Mac pixmap is clipped to visRgn defined by screenBits.bounds
° d ONLN d « t Ä > * Written: ° d ONLN d – t d Ä Ç )L1/1/90 ° d ONLN d ◊ Ä å ] ( ® 6Last reviewed: ° d ONLN d Ê Ä d å é )L11/21/90 ° d ONLN d Ô ò § k ( ¿ 6I’m drawing into ° d ONLN d ò k §⁄ )SJa large off-screen bitmap (pixmap), but anything drawn outside the 640- by ° d ONLN dK § ∞É ( à 6K480-pixel Macintosh screen area doesn’t get written to the pixmap. Why not? ° d ONLN dó ∞ º * * ___ ° d ONLN dõ » ‘@ *6When you create a new port with OpenPort or OpenCPort ° d ONLN d— »@ ‘⁄ ( ^ the visRgn is initialized to the ° d ONLN dÚ ‘ ‡9 ( ¸ 6<rectangular region defined by screenBits.bounds (IM I:163). ° d ONLN d. ‘9 ‡⁄ ( ¸W"If your port has a large portRect, ° d ONLN dQ ‡ Ï ( 6*any drawing will be clipped to the visRgn ° d ONLN d{ ‡ Ï⁄ )ÿ,and you will lose any drawing outside of the ° d ONLN d® Ï ¯ ° ( 6 screenBits.bounds rectangle. ° d ONLN d≈ ä *QTo correct this set the visRgn of the port to coincide with your port’s portRect ° d ONLN dä⁄ (,®after creating the ° d ONLN d) / (8 6port. ° d ONLN d/( 4 *5Also note that OpenPort initializes the clipRgn to a ° d ONLN dd(4⁄ (P8%wide-open rectangular region (-32768, ° d ONLN dä4 @ ˇ (\ 6--32768, 32767, 32767). Some operations, like ° d ONLN d∑4 ˇ@⁄ )Á-OpenPicture, can fail with this setup, so try ° d ONLN dÂ@ L … (h 6'setting clipRgn to a smaller rectangle. ° d ONLN d
X d > *X-Refs: ° d ONLN dd p4 * 8DTS Macintosh Technical Note “Pictures and Clip Regions” ° d ONLN dNp |o * CDTS Macintosh Technical Note “Drawing into an Off-Screen Pixel Map”
° d ONLN díî £π *';Using Macintosh System 7 OpenCPicture for higher resolution
° d ONLN dŒ£ Ø > * Written: ° d ONLN d◊£ dØ Ç )L1/1/90 ° d ONLN dfiØ ª ] (◊ 6Last reviewed: ° d ONLN dÌØ dª à )L12/7/90 ° d ONLN dı« ”O (Ô 6AWe want to use OpenCPicture for higher resolution, not for color ° d ONLN d6«O”⁄ (Ômper se. Can OpenCPicture in ° d ONLN dR” fl¨ (˚ 6OSystem 7 be used with non-Color as well as Color QuickDraw Macintosh computers? ° d ONLN d¢fl Î * * ___ ° d ONLN d¶˜ 3 *Yes, ° d ONLN d´˜ 3⁄ )Owith System 7, OpenCPicture can be used to create extended PICT2 files from all ° d ONLN d˚ ” (+ 6"Macintosh computers. Under System ° d ONLN d ”⁄ )ª26.0.7 or later, you must test for 32-Bit QuickDraw
° d ONLN dP (7 6&before using OpenCPicture. You can do ° d ONLN dv⁄ )¸ this by calling Gestalt with the ° d ONLN dó ' (C 60gestaltQuickdrawVersion selector. If it returns ° d ONLN d«'⁄ )ˆ&gestalt32BitQD or greater, then 32-Bit ° d ONLN dÓ' 3 á (O 6QuickDraw is installed. ◊ 4◊˘
*ù22 )
of 31 (ÏîColor QuickDraw Q&As ˇZ ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +Z-Developer Support Center ( -fi
December 1992 / X /
° d ONLN d ) < 8Y ( T Z(How to identify 32-Bit QuickDraw version
Iprintf ("We have Original QuickDraw version 0.%x\n", (feature & 0x00ff)); ° d ONLN dKR <] ˙ *
&else if ((feature & 0x0f00) == 0x0100) ° d ONLN dr\ <gö *
Fprintf ("We have 8 Bit QuickDraw version 1.%x\n", (feature & 0x00ff)); ° d ONLN dπf <q ˙ *
&else if ((feature & 0x0f00) == 0x0200) ° d ONLN d‡p <{ü *
Gprintf ("We have 32 Bit QuickDraw version 2.%x\n", (feature & 0x00ff)); ° d ONLN d(z <Ö P *
else ° d ONLN d-Ñ <è “ *
printf ("We don't have QD\n"); ° d ONLN dLé <ô A *
} ° d ONLN dNò <£ P *
else ° d ONLN dS¢ <≠ Ê *
"printf ("Gestalt err = %i\n",err); ° d ONLN dv¨ <∑ A *
} ° d ONLN dx∂ <¡ P *
else ° d ONLN d}¿ <À ¥ *
printf ("No Gestalt\n"); ° d ONLN dñ <’ A *
}
° d ONLN dòÏ <˚ƒ *&6Macintosh QDError function under System 6 and System 7
° d ONLN dœ˚ < b * Written: ° d ONLN dÿ˚ à ¶ )L1/1/90 ° d ONLN dfl < Å (/ ZLast reviewed: ° d ONLN dÓ à ¨ )L12/7/90 ° d ONLN dˆ <+ Ï (G Z Under what System 7 and System ° d ONLN d Ï+˛ )∞66 conditions is it legal to call the Macintosh QDError ° d ONLN dL+ <7 h (S Z function? ° d ONLN dV7 <C N * ___ ° d ONLN dZO <[ *&Under System 7, QDError can be called ° d ONLN dÄO[˛ )Δ0from all Macintosh computers. (System 7 supports ° d ONLN d±[ <gÕ (É ZCRGBForeColor, RGBBackColor, GetForeColor, and GetBackColor for all ° d ONLN dÙ[Õg˛ (ÉÎ Macintosh ° d ONLN d˛g <s q (è Z
computers ° d ONLN dg qs˛ )5Jas well.) On a non-Color QuickDraw Macintosh, QDError always returns a “no ° d ONLN dSs < Ó (õ Z error.” Under System 6, QDError ° d ONLN dss Ó˛ )≤0cannot be used for non-Color QuickDraw Macintosh ° d ONLN d§ <ã f (ß Zsystems. ◊ X◊
*EColor QuickDraw Q&As (Ï˙23 )
of 31 ˇ ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘
° d ONLN d ,ò *Macintosh CopyBits transfer modes changed for System 7
° d ONLN d 7 , 8 > * Written: ° d ONLN d @ , d 8 Ç )L1/1/90 ° d ONLN d G 8 D ] ( ` 6Last reviewed: ° d ONLN d V 8 d D à )L12/7/90 ° d ONLN d ^ P \
( x 6.Why do some Macintosh CopyBits transfer modes ° d ONLN d å P
\⁄ )Ú+produce different results for System 7 than ° d ONLN d ∏ \ h Z ( Ñ 6
for System 6? ° d ONLN d Δ h t * * ___ ° d ONLN d Ä åñ *LUnder System 6, the srcOr, srcXor, srcBic, notSrcCopy, notSrcOr, notSrcXor, ° d ONLN d Äñ å⁄ ( ®¥
Vall areas where the destination image was black and shows white in all areas where the ° d ONLN d tƒ –“ (Ï 6Ydestination image was white—roughly the opposite of what you see on an indexed pixel map. ° d ONLN d Œ‹ Ë¡ *LThe newer transfer modes addOver, addPin, subOver, subPin, adMax, and adMin ° d ONLN d
‹¡Ë⁄ (flwork ° d ONLN d
Ë Ù ` ( 6consistently at ° d ONLN d
/Ë `Ù⁄ )HMall pixel depths, and often, though not always, correspond to the theoretical ° d ONLN d
}Ù N ( 6>effect of the old transfer modes. For example, the adMin mode ° d ONLN d
ªÙN ⁄ ( l works similarly to the srcOr ° d ONLN d
ÿ ° (( 6Jmode on both direct and indexed pixel maps. Also, 1-bit deep source pixel ° d ONLN d " ° ⁄ ((ø maps work ° d ONLN d , ∏ (4 6Xconsistently and predictably regardless of the pixel depth of the destination even with ° d ONLN d Ñ ∏⁄ (4÷the old ° d ONLN d å $ b (@ 6transfer modes. ° d ONLN d ú0 <é *IUnder system software version 7.0, the old transfer modes now perform by ° d ONLN d Â0é<⁄ (X¨calculating with ° d ONLN d ˆ< H 9 (d 6colors ° d ONLN d ˝< 9H⁄ )!Trather than pixel values. You’ll find that transfer modes like srcOr and srcBic work ° d ONLN d RH T (p 61much more consistently even on direct pixel maps. ◊ 4◊˘
*|24 )
of 31 (ÏîColor QuickDraw Q&As ˇ6 ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +Z-Developer Support Center ( -fi
December 1992 / X /
° d ONLN d ) < 8r ( T Z+Which QuickDraw versions support SetEntries
° d ONLN d , 8 < D b * Written: ° d ONLN d 5 8 à D ¶ )L3/3/92 ° d ONLN d < D < P Å ( l ZLast reviewed: ° d ONLN d K D à P ¨ )L6/30/92 ° d ONLN d S \ < h r ( Ñ Z I’m calling ° d ONLN d _ \ r h˛ )6NSetEntries to update the on-screen CLUT. Who implements this call? Does 32-Bit ° d ONLN d Æ h < tñ ( ê ZBQuickDraw? In other words, does the 32-Bit QuickDraw INIT need to ° d ONLN d hñ t˛ ( ê¥be around for this to ° d ONLN d t < Ä ( ú Z%work? What about monochrome machines? ° d ONLN d- å < ò€ *UI’m creating off-screen buffers by hand instead of using GWorlds. Is this the proper ° d ONLN dÇ å€ ò˛ ( ¥˘way of ° d ONLN dâ ò < §˘ ( ¿ Z[doing off-screen buffering when we don’t want to require the user to have 32-Bit QuickDraw? ° d ONLN d § < ∞ N * ___ ° d ONLN dÈ º < »j *?SetEntries is part of the Color Manager, which exists with all ° d ONLN d( ºj »˛ ( ‰àColor QuickDraw versions. A ° d ONLN dD » < ‘Z ( Z<good rule of thumb to follow is that if it is documented in ° d ONLN dÄ »Z ‘{ ( xInside ° d ONLN dá »{ ‘¨ )! Macintosh ° d ONLN dê »¨ ‘˛ )1 Volume V, you ° d ONLN dü ‘ < ‡ ˜ ( ¸ Z'don’t need 32-Bit QuickDraw to use it. ° d ONLN dΔ ‘ ˜ ‡H )ªInside Macintosh ° d ONLN d÷ ‘H ‡K )Q ° d ONLN d◊ ‘K ‡˛ )!Volume V documents standard Color ° d ONLN d˘ ‡ < ÏX ( Z2QuickDraw. SetEntries does not work on monochrome ° d ONLN d+ ‡X Ï˛ (v Macintosh models, including the ° d ONLN dK Ï < ¯ € ( Z Classic II, SE, and PowerBooks. ° d ONLN dk < • *Off-screen buffering: ° d ONLN dÅ •˛ )iDYou should always use GWorlds if they exist; use Gestalt to test for ° d ONLN dΔ < È (8 ZUthem. This will assure that you can take advantage of the latest speed improvements. ° d ONLN dÈ ˛ (8It is ° d ONLN d! <(ı (D ZWimportant to remember that under System 7 NewGWorld and accompanying calls are present ° d ONLN dx ı(˛ (Din ° d ONLN d{( <4y (P Z?all Macintosh computers including black-and-white systems such ° d ONLN d∫(y4˛ (Póas Classic and PowerBook ° d ONLN d”4 <@ { (\ Z 100 systems.
° d ONLN d‡X <g *'+Macintosh pixel map maximum rowBytes change
° d ONLN d g <s b * Written: ° d ONLN dg às ¨ )L4/22/91 ° d ONLN d s < Å (õ ZLast reviewed: ° d ONLN d,s à ¨ )L6/10/91 ° d ONLN d4ã <ó Ÿ (≥ Z The Color QuickDraw section of ° d ONLN dSã Ÿó+ )ùInside Macintosh ° d ONLN dcã+ó˛ )R- Volume VI states that the restriction on the ° d ONLN dëó <£Î (ø ZWrowBytes field in a pixmap has been relaxed from $2000 to $4000. When did this happen? ° d ONLN dËóΣ˛ (ø Is it ° d ONLN dÓ£ <ؘ (À Z\true for all 32-Bit QuickDraw versions? This affects our user configuration recommendations. ° d ONLN dKØ <ª N * ___ ° d ONLN dO« <” *(The maximum rowBytes extension to $3FFF ° d ONLN dw«”˛ )ÿ/or less applies only to 32-bit QuickDraw. Using ° d ONLN dß” <fl (˚ Z)pixmaps with rowBytes greater than $1FFF ° d ONLN d–”fl˛ )“1when 32-bit QuickDraw is not present is likely to ° d ONLN dfl <Î à ( Zcause problems ° d ONLN dfl àβ )LHsuch as garbage images or system crashes. Remember that 32-bit QuickDraw ° d ONLN dZÎ <˜ Ë ( Z#is always present under System 7.0.
° d ONLN d~ < î *'3Use assembly to flip a 24-bit off-port color pixmap
° d ONLN d≤ <* b * Written: ° d ONLN dª à* ¶ )L5/7/91 ° d ONLN d¬* <6 Å (R ZLast reviewed: ° d ONLN d—* à6 ¨ )L7/25/91 ° d ONLN dŸB <N¢ (j ZMWhat’s the best approach to horizontally flip a 24-bit off-port color pixmap? ° d ONLN d'N <Z N * ___ ° d ONLN d+f <rÇ *BUnfortunately, you won’t be able to use CopyBits for this kind of ° d ONLN dmfÇr˛ (é†procedure; you’ll have to ° d ONLN dár <~ € (ö Z write your own routine to move ° d ONLN d¶r €~˛ )ü:each pixel. I’d suggest doing this in assembly language to ° d ONLN d·~ <äE (¶ Z7squeeze the best possible performance out of your code. ◊ X◊
*FColor QuickDraw Q&As (Ï˙25 )
of 31 ˇæ ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘
° d ONLN d ,í *:Construct a 'clut' instead of changing b/w palette entries
° d ONLN d ; , 8 > * Written: ° d ONLN d D , d 8 à )L6/10/91 ° d ONLN d L 8 D ] ( ` 6Last reviewed: ° d ONLN d [ 8 d D Ç )L8/1/91 ° d ONLN d b P \° ( x 6UHow can I change the first and last (white and black) entries in a Macintosh palette? ° d ONLN d ∏ \ h * * ___ ° d ONLN d º t ÄΔ *YThe answer to your question about changing the black and white entries in a palette is a ° d ONLN d tΔ Ä⁄ ( ú‰little ° d ONLN d Ä åÀ ( ® 6Zstrange. You can’t simply change the palette associated with an on-screen window, because ° d ONLN dv ÄÀ å⁄ ( ®Ètoo ° d ONLN dz å òŸ ( ¥ 6amany portions of the Toolbox/OS assume that the first entry is white and the last entry is black. ° d ONLN d‹ § ∞ z *However, what you ° d ONLN dÓ § z ∞ ä )bcan ° d ONLN dÒ § ä ∞ƒ )F do is create an off-screen GWorld and construct a 'clut' for it that ° d ONLN d7 §ƒ ∞⁄ ( Âdoes ° d ONLN d< ∞ º0 ( ÿ 6=what you want. Creating the 'clut' is fairly straightforward: ,
A (**offColors).ctTable [index].rgb.red = (index << 8) | index; ° d ONLN dÚ6 Ag *
C (**offColors).ctTable [index].rgb.green = (index << 8) | index; ° d ONLN d6@ Kb *
B (**offColors).ctTable [index].rgb.blue = (index << 8) | index; ° d ONLN dyJ U ' *
} ° d ONLN d}T _ ö *
(**offColors).ctFlags = 0; ° d ONLN dò^ i à *
$(**offColors).ctSeed = GetCTSeed ();
° d ONLN dΩt Äh *ENote that using this 'clut' with an off-screen GWorld will work fine ° d ONLN dthÄä (úÜexcept ° d ONLN d täÄ— )"if you attempt ° d ONLN dt—Ä⁄ )Gto ° d ONLN dÄ åo (® 6Fdraw text into the GWorld. Apparently drawing text off screen carries ° d ONLN daÄoå⁄ (®çthe same assumptions ° d ONLN dvå ò Æ (¥ 6 that all drawing does on screen. ° d ONLN dó§ ∞œ *XOnce you have done your off-screen drawing with the reversed 'clut' as described above, ° d ONLN dÔ§œ∞⁄ (ÃÌall ° d ONLN dÛ∞ º (ÿ 6Wthat remains is to CopyBits from your off-screen GWorld to your on-screen window. Your ° d ONLN dJ∞ º÷ (ÿËon ° d ONLN dL∞÷º⁄ ) - ° d ONLN dMº »< (‰ 6>screen window will need the appropriate palette. Fortunately, ° d ONLN dãº<»⁄ (‰Z"constructing that palette from the ° d ONLN dÆ» ‘ ] ( 6'clut' is trivial:
° d ONLN d¡‡ Î Æ * /* Make a palette out of it */ ° d ONLN d‡Í ıè *
° d ONLN d, Á **Attaching this palette to the window will ° d ONLN dV Á ⁄ )œ-cause the correct remapping to occur when you ° d ONLN dÑ ñ (4 6MCopyBits from the GWorld to the window, and everything should look just fine. ◊ 4◊˘
*∏26 )
of 31 (ÏîColor QuickDraw Q&As ˇÚ ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +Z-Developer Support Center ( -fi
December 1992 / X /
° d ONLN d ) < 8Δ ( T Z7Why PlotCIcon requires GetCIcon instead of Get1Resource
° d ONLN d 8 8 < D b * Written: ° d ONLN d A 8 à D ¨ )L4/26/91 ° d ONLN d I D < P Å ( l ZLast reviewed: ° d ONLN d X D à P ¨ )L6/17/91 ° d ONLN d ` \ < h § ( Ñ ZWhy do I have to use ° d ONLN d u \ § h˛ )hEGetCIcon(resID) instead of Get1Resource('cicn',resID) forPlotCIcon to ° d ONLN d ª h < t Ü ( ê Zwork correctly? ° d ONLN d À t < Ä N * ___ ° d ONLN d œ å < ò S *You ° d ONLN d ” å S ò˛ )[apparently thought something that, at first, I thought also: that GetCIcon(resID) is just a ° d ONLN d/ ò < §ô ( ¿ ZHutility routine that translates to Get1Resource('cicn',resID). However, ° d ONLN dw òô §˛ ( ¿∑this is not the case; ° d ONLN dç § < ∞/ ( à Z3GetCIcon not only gets the 'cicn' resource, but it ° d ONLN d¿ §/ ∞˛ )Û'also performs some minor surgery on the ° d ONLN dË ∞ < º ı ( ÿ Z*results, fills in some placeholder fields ° d ONLN d ∞ ı º˛ )π8in the resource data, and the like. Basically, PlotCIcon ° d ONLN dK º < ») ( ‰ Z1can’t work without the things that GetCIcon does.
° d ONLN d} ‡ < Ô⁄ *';CopyBits maps source pixmap colors to GDevice inverse table
° d ONLN dπ Ô < ˚ b * Written: ° d ONLN d¬ Ô à ˚ ¶ )L4/3/91 ° d ONLN d… ˚ < Å (# ZLast reviewed: ° d ONLN dÿ ˚ à ¨ )L6/17/91 ° d ONLN d‡ < ‰ (; ZWI’m trying to draw off screen so I made my own CGrafPort, pixmap, and color table, but ° d ONLN d7‰ ˛ (;when ° d ONLN d< <+~ (G ZDI draw into it, the colors come out all wrong. What’s going on here? ° d ONLN dÅ+ <7 N * ___ ° d ONLN dÖC <O £ *It’s a very common ° d ONLN dòC £O˛ )gCmisconception that CopyBits maps the colors available in the source ° d ONLN d‹O <[ø (w ZUpixmap’s color table to the colors available in the destination pixmap’s color table. ° d ONLN d2g <s ∏ *What actually happens is ° d ONLN dKg ∏s˛ )|@that CopyBits maps the colors in the source pixmap to the colors ° d ONLN dås << (õ Z6available in the current GDevice’s inverse table. See ° d ONLN d¬s<é (õZInside Macintosh ° d ONLN d“séª )R Volume ° d ONLN d⁄sª˛ )- V, pages 137 ° d ONLN dÁ <ãa (ß Z@through 139 for a description of inverse tables. Inverse tables ° d ONLN d'aã˛ (ß is a backwards color table. With ° d ONLN dHã <ó (≥ Z1a color table, you use a pixel value as an index ° d ONLN dyãó˛ )fi1into the table to return a color. With an inverse ° d ONLN d´ó <£6 (ø Z3table, you use a color-like value as an index into ° d ONLN dfió6£˛ )˙'the table to return a pixel value. When ° d ONLN d£ <Øò (À ZFCopyBits maps colors from one pixel map to another, it takes a source ° d ONLN dL£òØ˛ (À∂pixel value, uses the ° d ONLN dbØ <ªï (◊ ZJsource pixmap’s color table to get the corresponding color, and uses that ° d ONLN d¨Øïª˛ (◊≥color as an index into ° d ONLN d√ª <« („ Z'the current GDevice’s inverse table to ° d ONLN dͪ «˛ )¥;get the pixel value of the closest color in the destination ° d ONLN d&« <” † (Ô Zpixmap’s color table. ° d ONLN d<fl <Î) *2Generally speaking, every conceivable color table ° d ONLN dnfl)β )Ì-has exactly one conceivable inverse table. If ° d ONLN dúÎ <˜ ∞ ( Zyou alter the contents of ° d ONLN d∂Î ∞˜˛ )tIa color table, then the inverse table must likewise be altered. It’s just ° d ONLN d ˜ <∂ ( ZOlike numbers: for any number you give me, I can give you its negative. For any ° d ONLN dO˜∂˛ ( ‘color table you ° d ONLN d_ < Ó (+ Z!give me, MakeITable can give you ° d ONLN dÄ Ó· )≤/its inverse table. MakeITable is documented in ° d ONLN dØ·˛ )ÛInside ° d ONLN d∂ < m (7 Z Macintosh ° d ONLN dø m ÷ )1 Volume V, page 142. ° d ONLN d‘' <3 j (O Z Think of ° d ONLN d›' j3˛ ).Othe current GDevice as an implied parameter to CopyBits. If you don’t deal with ° d ONLN d -3 <?≤ ([ ZNGDevices at all, then the current GDevice is always the main screen’s GDevice ° d ONLN d {3≤?˛ ([–as far as you’re ° d ONLN d å? <K ë (g Zconcerned. Color ° d ONLN d ù? ëK˛ )UHQuickDraw often switches between different screens’ GDevices so that you ° d ONLN d ÊK <W € (s Z"can draw to multiple screens, but ° d ONLN d
K €W˛ )ü<that’s all handled behind your back. If you create a pixmap, ° d ONLN d
EW <c; ( Z9give it a color table, and CopyBits to it, then the main ° d ONLN d
~W;c˛ )ˇ(screen’s GDevice’s inverse table is used ° d ONLN d
ßc <o ô (ã Zto map colors from ° d ONLN d
∫c ôo˛ )]Gthe source pixmap. That’s OK as long as your destination pixmap’s color ° d ONLN d o <{ U (ó Ztable ° d ONLN d o U{˛ )Xis compatible with the main screen’s inverse table. If you change the depth and/or color ° d ONLN d a{ <á ≤ (£ Ztable of the main screen, ° d ONLN d {{ ≤Რ)vCand then still CopyBits to this same pixmap with the same old depth ° d ONLN d øá <ìN (Ø Z:and color table, then things won’t work correctly because ° d ONLN d ˘áNì˛ (Øl#the main screen’s GDevice’s inverse ° d ONLN d ì <üæ (ª ZRtable changes, making it incompatible with your destination pixmap’s color table. ° d ONLN d oìæü˛ (ª‹ This problem ° d ONLN d |ü <´Ü (« ZKusually manifests itself as incorrect colors, but it can result in crashes. ◊ X◊
*%Color QuickDraw Q&As (Ï˙27 )
of 31 ˇú ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘
° d ONLN d ) 5 s *$To fix this, you’ll ° d ONLN d ) s 5⁄ )[Ehave to remove your reliance on the main screen’s GDevice. To do that ° d ONLN d Z 5 A 7 ( ] 6you’ll ° d ONLN d a 5 7 A⁄ ) Qhave to make your own GDevice. There’s a routine called NewGDevice, but it always ° d ONLN d ≥ A M Ç ( i 6makes the GDevice in ° d ONLN d » A Ç M⁄ )jFthe system heap. Instead, you should just call NewHandle to allocate a ° d ONLN d M Y9 ( u 6<GDevice record yourself. Here’s what the fields should hold: ° d ONLN dL e q' *5gdRefNum—The GDevice has no driver, so set this to 0. ° d ONLN dÇ } â[ *EgdID—It doesn’t matter what this is set to—might as well set it to 0. ° d ONLN d» ï °Ã *\gdType—Set this to 2 if the off-screen uses direct colors (16 or 32 bits per pixel) or 0 if ° d ONLN d$ ïà °⁄ ( ΩÍthe ° d ONLN d( ° ≠" ( … 6;off-screen uses a color table (1 through 8 bits per pixel). ° d ONLN dd π ≈ È *(gdITable—Allocate a small (maybe just a ° d ONLN då π È ≈⁄ )—02-byte) handle for this field. After you’re done ° d ONLN dΩ ≈ — ∂ ( Ì 6!setting up this GDevice and your ° d ONLN dfi ≈ ∂ —⁄ )û<off-screen pixmap, color table (if any), and CGrafPort, then ° d ONLN d — ›F ( ˘ 6?set this GDevice as the current GDevice by calling SetGDevice. ° d ONLN dZ —F ›⁄ ( ˘d Then call MakeITable, passing ° d ONLN dx › ȃ ( 6^it NIL for both the color table and inverse table parameters, and 0 for the preferred inverse ° d ONLN d÷ ›ƒ È⁄ (‚table ° d ONLN d‹ È ı K ( 6 resolution. ° d ONLN dË
i *gdResPref—I’d ° d ONLN dˆ i
⁄ )QHguess that more than 99.9 percent of all inverse tables out there have a ° d ONLN d?
q é }ü )R8 Volume V) or by passing a handle to the color table to ° d ONLN dE qü }˛ ( ôΩCTabChanged. The ° d ONLN dV } < â Å ( • Znext time that ° d ONLN de } Å â˛ )EHpixmap is drawn into, Color QuickDraw will update your GDevice’s inverse ° d ONLN dÆ â < ïy ( ± ZGtable automatically when it realizes that the ctSeed is different from ° d ONLN dı ây ï˛ ( ±óthe current GDevice (which ° d ONLN d ï < ° ( Ω Z.had better be yours) inverse table’s iTabSeed. ° d ONLN d? ≠ < π *)GWorlds work this way on Color QuickDraw ° d ONLN dh ≠ π˛ )‹*machines. Every GWorld comes with a pixmap ° d ONLN dì π < ≈Ù ( · ZRand a GDevice. When you call SetGWorld, that sets both the GWorld and its GDevice ° d ONLN d πÙ ≈˛ ( ·as ° d ONLN dË ≈ < — a ( Ì Zcurrent.
° d ONLN dÒ È < ¯u *',How Macintosh system draws small color icons
° d ONLN d ¯ < b * Written: ° d ONLN d' ¯ à ¨ )L3/31/92 ° d ONLN d/ < Å (, ZLast reviewed: ° d ONLN d> à ¨ )L5/21/92 ° d ONLN dF <(“ (D ZTThe code I added to my application’s MDEF to plot small icons in color works except ° d ONLN dö “(˛ (Dfor when ° d ONLN d£( <4Ô (P ZXI hold the mouse over an item with color. The color of the small icons is wrong because ° d ONLN d˚(Ô4˛ (P
it’s ° d ONLN d 4 <@ ⁄ (\ Z!just doing an InvertRect. When I ° d ONLN d!4 ⁄@˛ )û:drag over the Apple menu, the menu inverts behind the icon ° d ONLN d\@ <L ‡ (h Z#but the icon is untouched. Is this ° d ONLN d@ ‡L˛ )§9done by brute force, redrawing the small icon after every ° d ONLN dπL <X r (t Z InvertRect? ° d ONLN d≈X <d N * ___ ° d ONLN d…p <|í *DAs you figured out, the Macintosh system draws color icons, such as ° d ONLN d
pí|˛ (ò∞the Apple icon on the ° d ONLN d#| <à (§ Z2menu bar, every time the title has to be inverted. ° d ONLN dVî <† ¬ * The actual sequence of calls ° d ONLN dsî ¬†˛ )ÜEis (more or less) as follows: first InvertRect is called to black the ° d ONLN dπ† <¨ Y (» Zmenu ° d ONLN dæ† Y¨˛ ) Ytitle and then PlotIconID is called to draw the icon in its place. The advantage of using ° d ONLN d¨ <∏Œ (‘ ZVPlotIconID is that you don’t have to worry about the depth and size of the icon being ° d ONLN dn¨Œ∏˛ (‘Ï used. The ° d ONLN dx∏ <ƒ. (‡ Z,system picks the best match from the family ° d ONLN d§∏.ƒ˛ )Ú%whose ID is being passed, taking into ° d ONLN d ƒ <– (Ï Zconsideration ° d ONLN dÿƒ –˛ )CPthe target rectangle and the depth of the device(s) that will contain the icon’s ° d ONLN d)– <‹ \ (¯ Zimage. ° d ONLN d0Ë <ÙH *8The Icon Utilities call PlotIconID is documented in the ° d ONLN dhËHÙ˛ (f"Macintosh Technical Note, “Drawing ° d ONLN dãÙ < ‚ ( ZZIcons the System 7 Way.” Just in case you don’t have your stack at hand, the interface is: ,
Courier
° d ONLN dÊ < ˙ *& IconAlignmentType = INTEGER; ° d ONLN d
<! ˙ *
& IconTransformType = INTEGER; ° d ONLN d 4* <5 ˙ *& FUNCTION PlotIconID(theRect: Rect; ° d ONLN d [4 <?1 *
1 align: IconAlignmentType; ° d ONLN d ç> <IE *
5 transform: IconTransformType; ° d ONLN d √H <S6 *
2 theResID: INTEGER): OSErr; ° d ONLN d ˆR <] ˙ *
& INLINE $303C, $0500, $ABC9; ° d ONLN d
"f <q Î *#typedef short IconAlignmentType; ° d ONLN d
Fp <{ Î *
#typedef short IconTransformType; ° d ONLN d
jÑ <è *,pascal OSErr PlotIconID(const Rect *theRect, ° d ONLN d
óé <ô@ *
4 IconAlignmentType align, ° d ONLN d
Ãò <£T *
8 IconTransformType transform, ° d ONLN d ¢ <≠ *
+ short theResID) ◊ X◊
*#Color QuickDraw Q&As (Ï˙29 )
of 31 ˇP ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘ ,
Courier
° d ONLN d ( ≥ * = {0x303C, 0x0500, 0xABC9};
° d ONLN d 3 ?ô *SPlease refer to the Tech Note referenced above for more details on using the calls.
° d ONLN d t W f∞ *'8Spooling and preserving Macintosh QuickDraw pixmap depth
settings) ° d ONLN d˘ Í D ˆ⁄ ),Mof the devices the target port may span (as when a window crosses two or more ° d ONLN dG ˆ C ( 6 screens). ° d ONLN dQ Ü *If there’s not enough ° d ONLN dg Ü⁄ )n?memory in the application heap or in the temporary memory pool, ° d ONLN dß & Å (B 6QuickDraw bands the ° d ONLN dª Å&⁄ )iFimage down to one scan line and calls StdBits for each of these bands. ° d ONLN d& 2ƒ (N 6[Note that if you’re providing your own bitsProc, QuickDraw will call it instead of StdBits. ° d ONLN d^> JM *AThis process is the same when the picture is in memory, with the ° d ONLN dü>MJ⁄ (fk obvious exception that all the ° d ONLN dæJ VÇ (r 6Npicture data is present; the color mapping occurs when StdBits does its stuff.
() 65can get at this by searching for the headerOp opcode ° d ONLN d»
⁄ )˘+in the picture data (it’s always the second ° d ONLN dÙ
(5 69opcode in the picture data, but you still have to search ° d ONLN d-
⁄ (56)for it in case there are any zero opcodes ° d ONLN dW %ò (A 6Ubefore it). Or you can use the Picture Utilities Package to extract this information. ° d ONLN d≠1 = *8With older picture formats, the resolution and original ° d ONLN dÂ1=⁄ (Y7&bounds information is sometimes not as ° d ONLN d = I o (e 6obvious or easily ° d ONLN d = oI⁄ )WJderived. In fact, in some applications, the PICT’s resolution and original ° d ONLN d iI U (q 66bounds aren’t stored in the header, but rather in the ° d ONLN d üI U⁄ )Ù+pixel map structure(s) contained within the ° d ONLN d ÀU a 6 (} 6PICT. ° d ONLN d —m yÄ *JTo examine these pixmaps, you’ll first need to install your own bitsProc, ° d ONLN d
mÄy⁄ (ïûand then manually ° d ONLN d
-y Ö ˝ (° 6/check the bounds, hRes, and vRes fields of any ° d ONLN d
\y ˝Ö⁄ )Â+pixmap being passed. In most cases the hRes ° d ONLN d
àÖ ë¡ (≠ 6Mand vRes fields will be set to the Fixed value 0x00480000 (72 dpi); however, ° d ONLN d
’Ö¡ë⁄ (≠flsome ° d ONLN d
⁄ë ùŒ (π 6_applications will set these fields to the PICT’s actual resolution, as shown in the code below. ◊ 4◊˘
*330 )
of 31 (ÏîColor QuickDraw Q&As ˇX ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +Z-Developer Support Center ( -fi
December 1992 / X / ,
Courier
° d ONLN d < ( » ( D Z Rect gPictBounds; ° d ONLN d ' < 2 ˙ *
&Fixed gPictHRes, gPictVRes; ° d ONLN d D ; < Fc *;pascal void ColorBitsProc (srcBits, srcRect, dstRect, mode, ° d ONLN d Å E < P x *
3 DrawPicture (picture, &((**picture).picFrame)); ° d ONLN d≈
< Î *
# (*(qd.thePort)).grafProcs = 0L; ° d ONLN dÈ <" A *
} ◊ X◊
(Ï ZColor QuickDraw Q&As (Ï˙31 )
of 31 ˇ> ◊# ˇ ˇˇˇˇ # ◊ † Ç
/ Z Å#
0Ià:µú9 " { ˇˇˇˇˇˇˇˇ # † ƒ ° d
ONLN f ˛ † å ° d 1drw2 … -·_ Ä ˇˇˇˇˇˇ è ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˙ ó@ † ò , Times
. R… R… +]BNew Technical Notes † ô ° d drw2 : °„ † ó ° d 1drw2 eÙ Ä ˇˇˇˇˇˇ P ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä E¿ † ò
( {ïDeveloper Support † ô ° d drw2 : °„ † ó ° d `drw2 - Ô ˇˇˇˇˇˇ K Ô - Z f f Z ° d 1drw2 ¿˙È ˇˇˇˇˇˇ K ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : 0 ° ö ˇÙ Ä † ò
0 ( UÔ † ô ° d drw2 : °„ † ó ° d 1drw2 ÔÊ˙ ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˝Ä † ò
+& ® † ô ° d drw2 : °„ † ó ° d 1drw2  -¯ y ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä % † ò
( Z \ Macintosh † ô ° d drw2 : °„ † ó † ç ° d drw2 D † É
IR . ° d ONLN d z < ç, ( ß ZAdding Color With CopyBits
° d ONLN d å < õ r *Imaging ° d ONLN d # år õ˛ ( ∑êM.IM.ColorCopyBits
° d ONLN d 6 ß < ≥ q ( œ Z
Revised by ° d ONLN d B ß≈ ≥˛ ( œ„
March 1988 ° d ONLN d M ≥ < ø q ( € Z Written by: ° d ONLN d Y ≥ Ñ ø ≈ )H
Chris Derossi ° d ONLN d g ≥± ø˛ ( €œ
November 1987 ° d ONLN d u À < ◊ ¿ ( Û ZInside Macintosh Volume V ° d ONLN d é À ¿ ◊Q )Ñ states that the foreground and ° d ONLN d Æ ÀQ ◊˛ )ë#background colors are applied to an ° d ONLN d “ ÿ < ‰ Ö ( Zimage during a ,
Courier ° d ONLN d · ◊ Ö „ Ω )ICopyBits ° d ONLN d È ÿ Ω ‰ Õ )8 or ° d ONLN d Ì ◊ Õ „ )CopyMask ° d ONLN d ı ÿ ‰á )8 call. Accidental use of this ° d ONLN d ÿá ‰˛ )Çfeature can create bizarre ° d ONLN d. ‰ < ˆ ( Z\coloring effects. This note explains what happens, how to avoid problems, and how to use it. X
° d ONLN dã <$ ô *4 What Happens
° d ONLN dò0 << Æ *Color QuickDraw has a ° d ONLN dÆ0 Æ<˛ )rDfeature that will allow you to convert a monochrome image to a color ° d ONLN dÛ= <I ã (e Zimage. During a ° d ONLN d< ãH √ )OCopyBits ° d ONLN d = √I Δ )8 ° d ONLN d = ΔI ‘ )or ° d ONLN d< ‘H )CopyMask ° d ONLN d= I˛ )82 call, if the foreground and background colors are ° d ONLN dJI <U‘ (q ZTnot black and white, respectively, Color QuickDraw performs the following operation ° d ONLN dûI‘U˛ (qÚon every ° d ONLN dßU <a ï (} Zpixel being copied:
° d ONLN dºn `y +$%NOTE: color table index = pixel value ° d ONLN d„Ç `ç *%s = color table index of source pixel ° d ONLN d
å `ó2 *
*fg = color table index of foreground color ° d ONLN d6ñ `°2 *
*bg = color table index of background color ° d ONLN db™ `µU *1ColoredPixelValue = (NOT(s) AND bg) OR (s AND fg)
° d ONLN dî¿ <Ã0 (Ë Z3If your source image contains only black and white ° d ONLN d«¿0Ã˛ )Ù*pixels, then all black pixels would become ° d ONLN dÚà <ÿF (Ù Z7the foreground color and all white pixels would become ° d ONLN d)ÃFÿ˛ (Ùd%the background color. This is because ° d ONLN dOÿ <‰◊ ( Z]the color table index for white is all zeros and the color table index for black is all ones. ° d ONLN d≠Ò <˝m *>For example, suppose your source image was a 4-bit deep color ° d ONLN dÎm¸ó (ãPixMap ° d ONLN dÒÒó˝û )*. ° d ONLN dÛÒû˝˛ )Then the color table ° d ONLN d˝ < ” (% ZWindex for white (in binary) is 0000 and the index for black is 1111. And let’s suppose ° d ONLN d_˝” ˛ (%Ò that your ° d ONLN di <Û (1 ZXforeground color is green with an index of 1101 while your background color is red with ° d ONLN d¡ Û˛ (1an ° d ONLN dƒ <!ë (= ZGindex of 0011. Then for the black pixels, the above procedure produces:
° d ONLN d
- `8á +$;ColoredPixelValue = (NOT(1111) AND 0011) OR (1111 AND 1101) ° d ONLN dJ7 `Bá *
; 1101 = ( 0000 AND 0011) OR (1111 AND 1101)
° d ONLN dÜM <Y (u Z-And the operation on the white pixels yields:
° d ONLN dµf `qá +$;ColoredPixelValue = (NOT(0000) AND 0011) OR (0000 AND 1101) ° d ONLN dÚp `{á *
; 0011 = ( 1111 AND 0011) OR (0000 AND 1101) ◊ X◊
(Ï ZAdding Color With CopyBits (Ï1 ) of 3 ˇ ° ¿Ù%%DSIDICT:_cv
currentdict /bu known {bu}if
userdict /_cv known not{userdict /_cv 30 dict put}if
_cv begin
/bdf{bind def}bind def
currentscreen/cs exch def/ca exch def/cf exch def
/setcmykcolor where{/setcmykcolor get /cvcmyk exch def}{/cvcmyk{1 sub 4 1 roll 3{3 index add neg dup 0 lt{pop 0}if 3 1 roll}repeat setrgbcolor pop}bdf }ifelse
/ss{//cf //ca //cs setscreen}bdf
/stg{ss setgray}bdf
/strgb{ss setrgbcolor}bdf
/stcmyk{ss cvcmyk}bdf
/min1{dup 0 eq{pop 1}if}bdf
end
currentdict /bn known {bn}if
† ø∫ ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘
° d ONLN d ) 8 ë *'Possible Problems
° d ONLN d D PG *AThis colorizing will only work on 2-color (i.e. black and white) ° d ONLN d S DG P⁄ ( le images, and then only if those ° d ONLN d r P \ Ñ ( x 6colors occupy the first ° d ONLN d ä P Ñ \⁄ )lKand last entries in the color table. Trying to colorize colors that are not ° d ONLN d ÷ \ hF ( Ñ 6Ethe first and last color table entries will yield unexpected results. ° d ONLN d t Äm *LThis is mainly due to the fact that the colorizing algorithm uses a pixel’s ° d ONLN dh tm Ä⁄ ( úãcolor table index value ° d ONLN dÄ Ä å ( ® 60rather than its actual RGB color. To illustrate ° d ONLN d∞ Ä å⁄ )˜&this, let’s assume that foreground and ° d ONLN d◊ å òy ( ¥ 6Fbackground colors are as above, and your image contains yellow with a ° d ONLN d åy ò⁄ ( ¥ócolor table index of ° d ONLN d2 ò §  ( ¿ 6*1000. The colorizing operation would give: ,
Courier
° d ONLN d^ ∞ < ªc +$;ColoredPixelValue = (NOT(1000) AND 0011) OR (1000 AND 1101) ° d ONLN dõ ∫ < ≈c *
; 1011 = ( 0111 AND 0011) OR (1000 AND 1101)
° d ONLN d◊ – ‹ï ( ¯ 6NSince the color table may have any RGB color at the resulting index position, ° d ONLN d% –ï ‹⁄ ( ¯≥the final color ° d ONLN d5 ‹ Ëk ( 6Fmay not even be close to the source, foreground, or background colors. ° d ONLN d| Ù é *PSimilar things occur if you are trying to colorize a black and white image when ° d ONLN dà Ùé ⁄ ( ¨white and black ° d ONLN d‹ , (( 6>do not occupy the first and last positions in the color table. ° d ONLN d % ê *The bottom line rules for ° d ONLN d5 ê$ » )xCopyBits ° d ONLN d= »%s )8%ing in a color environment are these: ° d ONLN dc1 *= . (Y H• ° d ONLN de1 7=º )
OThou shalt set thy background color to white and thy foreground color to black ° d ONLN d¥1º=⁄ (Y⁄before ° d ONLN dª> 7J Y (f Ucalling ° d ONLN d√= YI ë )"CopyBits ° d ONLN dÀ> ëJ ° )8 or ° d ONLN dœ= °I Ÿ )CopyMask ° d ONLN d◊> ŸJª )8., unless thou art coloring a monochrome image. ° d ONLN dV *b . (~ H• ° d ONLN dV 7b∂ )
QThou shalt, when colorizing, make sure that the first color table entry is white ° d ONLN dYV∂b⁄ (~‘and the ° d ONLN dab 7n J (ä Ulast ° d ONLN dgb `n ◊ ))color table entry is black. ° d ONLN dÉz Ü. (¢ 6<The second rule is easy to follow because the default color ° d ONLN døz.Ü⁄ (¢L$tables are constructed properly, and ° d ONLN d‰Ü í v (Æ 6if you are using the ° d ONLN d˘Ü ví⁄ )^KPalette Manager (and you are, right?) then it will make sure that the color ° d ONLN dEí û z (∫ 6tables obey this rule.
° d ONLN d\∂ ≈ Í *'How To Colorize—An Example
° d ONLN dw— › ò *This code fragment shows ° d ONLN dê— ò›⁄ )ÄDhow to implement a color fill, like the paint bucket in MacPaint. It ° d ONLN d’fi Í ü ( 6 relies on three main things: ° d ONLN dÚ› üÈ fi )á SeedCFill ° d ONLN d˚fi fiÍh )? for calculating the fill area, ° d ONLN d›hȆ )äCopyMask ° d ONLN d#fi†Í∂ )8 for ° d ONLN d(fi∂Í⁄ )actually ° d ONLN d1Í ˆ Ô ( 6,changing the bits, and QuickDraw colorizing.
° d ONLN d^
: *:PROCEDURE PaintBucket(where: Point; paintColor: RGBColor); ° d ONLN dö <! K +$VAR ° d ONLN d† `+ É +$
savedFG ° d ONLN d® ®+ fl )H : RGBColor; ° d ONLN d∂* `5 É (Q ~offBits ° d ONLN dæ* ®5 ’ )H : BitMap; ° d ONLN d…> <I U (e ZBEGIN ° d ONLN d—H `S +$
${First, create an offscreen bitmap.} ° d ONLN d¯R `] *
%offBits.bounds := myWindow^.portRect; ° d ONLN d \ `g Ï *
WITH offBits.bounds DO BEGIN ° d ONLN d@f Ñqç +$
5offBits.rowBytes := ((right - left + 15) DIV 16) * 2; ° d ONLN dyp Ñ{∞ *
<offBits.baseAddr := NewPtr((bottom-top) * offBits.rowBytes); ° d ONLN d∏z `Ö t (° ~END; ° d ONLN døé `ôZ *2{Check MemError here! Make sure NewPtr succeeded!} ◊ 4◊˘
(Ï 62 ) of 3 (ÏÇAdding Color With CopyBits ˇ à ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +Z-Developer Support Center ( -Ï
March 1988 / X / ,
Courier
° d ONLN d ' Ñ 2ú ( N ¢8SeedCFill(myWindow^.portBits,offBits,myWindow^.portRect, ° d ONLN d < 1 ® <z +$
*myWindow^.portRect,where.h,where.v,NIL,0); ° d ONLN d i ; Ñ F Ú ( b ¢GetForeColor(savedFG); ° d ONLN d Ç E Ñ P *
RGBForeColor(paintColor); ° d ONLN d û O Ñ Zø *
?CopyMask(offBits,offBits,myWindow^.portBits,myWindow^.portRect, ° d ONLN d · Y ® dk +$
'myWindow^.portRect,myWindow^.portRect); ° d ONLN d c Ñ n Ú ( ä ¢RGBForeColor(savedFG); ° d ONLN d$ w Ñ Ç * DisposPtr(offBits.BaseAddr); ° d ONLN dB Å ` å t ( ® ~END;
° d ONLN dG ò < § É ( ¿ Z
The variable ° d ONLN dT ó É £ ¥ )GoffBits ° d ONLN d[ ò ¥ § )1 is an offscreen ° d ONLN dl ó £= )_BitMap ° d ONLN dr ò= §E )* ° d ONLN ds òE §o )(not a ° d ONLN dz óo £ô )*PixMap ° d ONLN dÄ òô §ƒ )*) with ° d ONLN dá óƒ £Ó )+bounds ° d ONLN dç òÓ §˛ )* = ° d ONLN dê § < ∞ ∫ ( Õ ZmyWindow^.portRect ° d ONLN d¢ • ∫ ± » )~. ° d ONLN d• § » ∞ ) SeedCFill ° d ONLN dÆ • ±y )? effectively creates, in ° d ONLN d« •y ±ø )rthe offscreen ° d ONLN d’ §ø ∞È )FBitMap ° d ONLN d€ •È ±˛ )*, a ° d ONLN d‡ ≤ < æ_ ( ⁄ Z:monochrome image of the bits that we want to paint. Since ° d ONLN d ±_ Ωê ( ⁄}offBits ° d ONLN d! ≤ê æÌ )1 contains the exact ° d ONLN d5 ≤Ì æ˛ )]bits ° d ONLN d: ø < Àõ ( Á ZLthat we want to paint, it is used as both the source image and the mask for ° d ONLN dÜ æõ ” ( ÁπCopyMask ° d ONLN dé ø” À◊ )8. ° d ONLN dê ◊ < „ ( ˇ ZaBy setting the foreground color to the desired paint color, the result is a colorized version of ° d ONLN dÒ ◊ „˛ ( ˇthe ° d ONLN dı ‰ < • ( Zmask (the paint area) ° d ONLN d ‰ • J )i being copied onto the window’s ° d ONLN d* „J Ôt )•PixMap ° d ONLN d0 ‰t ˛ )* without affecting any other ° d ONLN dM < ¸ Q ( Zbits. ° d ONLN dS <, ¶ *0Further Reference: K XK ° d ONLN df- N9 R +
• ° d ONLN dh- `9 ¥ )Color QuickDraw ◊ X◊
(Ï ZAdding Color With CopyBits (Ï3 ) of 3 ˇÍ ◊# ˇ ˇˇˇˇ # ◊ ° d WORD S † å ° d WORD R… † Ç
/ Z Å#
0Ià:µú9 " { ˇˇˇˇˇˇˇˇ # † ƒ ° d
ONLN f ˛ † å ° d 1drw2 … -·_ Ä ˇˇˇˇˇˇ è ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˙ ó@ † ò , Times
. ^ tK^ tK +]BNew Technical Notes † ô ° d drw2 : °„ † ó ° d 1drw2 eÙ Ä ˇˇˇˇˇˇ P ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä E¿ † ò
Ä ( {ïDeveloper Support † ô ° d drw2 : °„ † ó ° d `drw2 - Ô ˇˇˇˇˇˇ K Ô - Z f f Z ° d 1drw2 ¿˙È ˇˇˇˇˇˇ K ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : 0 ° ö ˇÙ Ä † ò
0 ( UÔ † ô ° d drw2 : °„ † ó ° d 1drw2 ÔÊ˙ ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˝Ä † ò
l +& ® † ô ° d drw2 : °„ † ó ° d 1drw2  -¯ y ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä % † ò
BÄ ( Z \ Macintosh † ô ° d drw2 : °„ † ó † ç ° d drw2 D † É ° d WORD † ç
IR . ° d ONLN d { < éœ ( ® Z+Deaccelerated _CopyBits & 8•24 GC QuickDraw
° d ONLN d , ç < ú r *Imaging ° d ONLN d 4 ço ú˛ ( ∏çM.IM.GCQDCopybits
° d ONLN d F ® < ¥ q ( – Z Written by: ° d ONLN d R ® Ñ ¥ › )HGuillermo A. Ortiz ° d ONLN d e ®∏ ¥˛ ( –÷
February 1991 ° d ONLN d s ¡ < Õ “ ( È Z This Technical Note discusses ° d ONLN d ë ¡ “ ÕV )ñconditions that may cause ,
Courier ° d ONLN d ´ ¿V Ãï )Ñ _CopyBits ° d ONLN d ¥ ¡ï Õ˛ )? to slow down when ° d ONLN d « Õ < Ÿy ( ı Z@QuickDraw acceleration is on via the Apple 8•24 GC Display Card. X
° d ONLN d™¡ <–û *'._CopyBits Conforms To The Same Scheme, Except…
° d ONLN dŸ‹ <Ë { * _CopyBits ° d ONLN d‚› {È )?" conforms to the same operational ° d ONLN d› È˛ )¢-scheme, but there are some instances in which ° d ONLN d2È <ı â ( Z
GC QuickDraw ° d ONLN d?È âı˛ )MRcannot perform the call in parallel; in this cases it is even possible to suffer a ° d ONLN díı < ¿ ( Z performance loss, since the ° d ONLN dÆı ¿˛ )Ñ@whole call may have to be completed before control is given back ° d ONLN dÔ <‚ (* ZVto the application and GC QuickDraw has to make calls and access data across the NuBus
° d ONLN dE ‚ Í (' ™
° d ONLN dFÍÓ +. ° d ONLN dH <&∏ (B ZNThe situations that compromise GC QuickDraw parallel operation are as follows: ° d ONLN dó3 N? R +• ° d ONLN dô3 [? )
"When the destination device has a ° d ONLN dª2>I )®
SearchProc ° d ONLN d≈3I?¬ )F installed and the source ° d ONLN dfl3¬?⁄ )ycolor ° d ONLN dÂ? [Ko (g y:environment is different from the destination environment. ° d ONLN d!X [d ∞ *QuickDraw calls ° d ONLN d1X ∞d ª )Ua ° d ONLN d3W ªc )
SearchProc ° d ONLN d=Xd⁄ )F) whenever the source and destination have ° d ONLN dgd [p (å y&different depths and when two indexed ° d ONLN dçd p⁄ )¡'pixel maps have different color tables, ° d ONLN dµp [| ˝ (ò y even though their depths may be ° d ONLN d’p ˝|⁄ )¢,identical. When GC acceleration is enabled, ° d ONLN d| [à ÿ (§ ythese conditions cause the ° d ONLN d | ÿà⁄ )}3following two types of behavior, dependent upon the ° d ONLN dQà [î Æ (∞ ysource pixel map: ◊ X◊
userdict /_cv known not{userdict /_cv 30 dict put}if
_cv begin
/bdf{bind def}bind def
currentscreen/cs exch def/ca exch def/cf exch def
/setcmykcolor where{/setcmykcolor get /cvcmyk exch def}{/cvcmyk{1 sub 4 1 roll 3{3 index add neg dup 0 lt{pop 0}if 3 1 roll}repeat setrgbcolor pop}bdf }ifelse
/ss{//cf //ca //cs setscreen}bdf
/stg{ss setgray}bdf
/strgb{ss setrgbcolor}bdf
/stcmyk{ss cvcmyk}bdf
/min1{dup 0 eq{pop 1}if}bdf
end
currentdict /bn known {bn}if
† øv ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘
° d ONLN d < ) @ +$• ° d ONLN d I )2 )
/If the source is an indexed pixel map, then GC ° d ONLN d 1 2 )® )ÈQuickDraw executes the ° d ONLN d H * I 6
( R g,part of the setup that involves calling the ,
Courier ° d ONLN d t )
5P )¡
SearchProc ° d ONLN d ~ *P 6ü )F, returns control ° d ONLN d ê *ü 6® )Oto ° d ONLN d ì 6 I B ¿ ( ^ gthe main processor, then ° d ONLN d ¨ 6 ¿ B® )w3completes the call in parallel. The act of calling ° d ONLN d ‡ C I O \ ( k gthe ° d ONLN d ‰ B \ N ¢ )
SearchProc ° d ONLN d Ó C ¢ O )F before returning control ° d ONLN d C O® )~makes the call slower than ° d ONLN d# P I \ y ( x gwhen no ° d ONLN d+ O y [ ø )0
SearchProc ° d ONLN d5 P ø \ ƒ )F ° d ONLN d6 P ƒ \® ).is involved, since parallel operation does not ° d ONLN de \ I h ‚ ( Ñ g occur throughout the whole call. ° d ONLN dÜ t < Ä @ ( ú Z• ° d ONLN dà t I Ä T )
SearchProc ° d ONLN d› Å † ç ¥ )F for ° d ONLN d‚ Å ¥ ç® )3every pixel that is drawn, and the application does ° d ONLN d é I ö ˇ ( ∂ g+not regain control until after the call to ° d ONLN dA ç ˇ ô> )∂ _CopyBits ° d ONLN dJ é> ö° )? has been completed. ° d ONLN d_ ß * ≥ . ( œ H• ° d ONLN da ß 7 ≥u )
DWhen the source or destination is offscreen and not created using a ° d ONLN d• ¶u ≤ü ( œìGWorld ° d ONLN d´ ßü ≥£ )*. ° d ONLN dÆ ø 7 À Á ( Á U"GC QuickDraw has no way to detect ° d ONLN d– ø Á À∂ )∞*when an application is going to manipulate ° d ONLN d˚ À 7 ◊* ( Û U6a pixel map it has created in memory, so if it has to ° d ONLN d1 À* ◊∂ )Ûdraw to or copy from such a ° d ONLN dM ◊ 7 „ a ( UPixMap ° d ONLN dS ÿ a ‰ ‘ )*, GC QuickDraw has to ° d ONLN di ÿ ‘ ‰∂ )s/complete the operation before returning control ° d ONLN dô ‰ 7 ã ( Uto the application. ° d ONLN dÆ ˝ 7 D *3This behavior is contrary to the case when using a ° d ONLN d· ¸Dn (%bGWorld ° d ONLN dÁ ˝n ∂ )* for offscreen ° d ONLN dˆ
7 ~ (2 Uenvironments, ° d ONLN d
~ Ë )Gsince in the case of a ° d ONLN d Ë )jGWorld ° d ONLN d!
∂ )* , GC QuickDraw is alerted by the ° d ONLN dB 7# \ (? Ucall to ° d ONLN dJ \" ≈ )%_GetPixBaseAddr ° d ONLN dY ≈#É )i' that the application is getting ready ° d ONLN dÄÉ#∂ )æ to directly ° d ONLN då# 7/ (K U.change the pixels. This is the reason why it ° d ONLN d∫# /∂ )“&is so important that applications call ° d ONLN d·/ 7; † (X U_GetPixBaseAddr ° d ONLN d0 †< £ )i ° d ONLN dÒ0 £< ¬ )every ° d ONLN dˆ0 ¬< ‹ ) time ° d ONLN d¸0 ‹<q ) they are about to manipulate a ° d ONLN d/q;õ )ïGWorld ° d ONLN d!0õ<∂ )* pixel ° d ONLN d(< 7H u (d U
map directly. ° d ONLN d6U *a . (} H• ° d ONLN d8U 7a è )
When the source ° d ONLN dHT è` π )XPixMap ° d ONLN dNU πaE )* has a color table that uses ° d ONLN dkUEa∂ )åindexes that refer to a ° d ONLN dÉa 7m Y (â Upalette. ° d ONLN dçy 7Ö p *
SearchProc ° d ONLN d–®‹∂ )F is ° d ONLN dÉ‹ 7Ëa ( UDinvolved; therefore, it only implies a partial loss of parallelism; ° d ONLN d«‹aË∂ (it is good to keep ° d ONLN d⁄È 7ı5 ( U6in mind that this case can only occur when the source ° d ONLN dË5Ù_ )˛PixMap ° d ONLN dÈ_ıñ )* is indexed. ° d ONLN d# % Ç (A 6Further Reference: D 4D˘ ° d ONLN d6& *2 . +
• ° d ONLN d8& <2 ç )Inside Macintosh ° d ONLN dH& ç2? )Q!, Volumes V & VI, Color QuickDraw ° d ONLN dj2 *> . (Z H• ° d ONLN dl2 <> s )
d e v e l o p ° d ONLN dy2 s>∑ )7@, “Macintosh Display Card 8•24 GC: The Naked Truth,” July 1990. ° d ONLN d∫> *J . (f H• ° d ONLN dº> <Jh )<Technical Note #275, 32-Bit QuickDraw: Version 1.2 Features ° d ONLN d˘J *V . (r H• ° d ONLN d˚J <V≥ )FDeveloper Notes for the Macintosh Display Cards 4•8, 8•24 and 8•24 GC ° d ONLN d AJ≥V⁄ (r—(APDA, ° d ONLN d HV <b | (~ Z
M085TLL/A) ° d ONLN d Sn z Í (ñ 6*NuBus is a trademark of Texas Instruments. ◊ 4◊˘
*V2 ) of 2 )˙+Deaccelerated _CopyBits & 8•24 GC QuickDraw ˇ¬ ◊# ˇ ˇˇˇˇ # ◊ ° d WORD S † å ° d WORD R… † Ç
/ Z Å#
0Ià:µú9 " { ˇˇˇˇˇˇˇˇ # † ƒ ° d
ONLN f ˛ † å ° d 1drw2 … -·_ Ä ˇˇˇˇˇˇ è ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˙ ó@ † ò , Times
. eRSeRS +]BNew Technical Notes † ô ° d drw2 : °„ † ó ° d 1drw2 eÙ Ä ˇˇˇˇˇˇ P ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä E¿ † ò
Ä ( {ïDeveloper Support † ô ° d drw2 : °„ † ó ° d `drw2 - Ô ˇˇˇˇˇˇ K Ô - Z f f Z ° d 1drw2 ¿˙È ˇˇˇˇˇˇ K ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : 0 ° ö ˇÙ Ä † ò
0 ( UÔ † ô ° d drw2 : °„ † ó ° d 1drw2 ÔÊ˙ ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˝Ä † ò
l +& ® † ô ° d drw2 : °„ † ó ° d 1drw2  -¯ y ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä % † ò
BÄ ( Z \ Macintosh † ô ° d drw2 : °„ † ó † ç ° d drw2 D † É ° d WORD † ç
IR . ° d ONLN d { < é ¥ ( ® Z
Drawing Icons
° d ONLN d ç < ú r *Imaging ° d ONLN d çx ú˛ ( ∏ñM.IM.DrawingIcons
° d ONLN d ( ® < ¥ q ( – Z Written by: ° d ONLN d 4 ® Ñ ¥ Œ )HJim Friedlander ° d ONLN d D ®æ ¥˛ ( –‹ October 1985 ° d ONLN d Q ¡ < Õ Ú ( È Z$Using resources of type ICON allows ° d ONLN d u ¡ Ú ÕU )∂drawing of icons in ,
An ICON is a ° d ONLN d: ˇ < È (' Z[32 by 32 bit image of an icon and can be drawn using the following Toolbox Utilities calls:
° d ONLN dó `" Ò +$ MyIconHndl:= GetIcon(iconID); ° d ONLN d∂! `, ‚ *
PlotIcon(destRect,iconID);
° d ONLN d—7 <Ci (_ Z>While very convenient, this method only allows the drawing of ° d ONLN d7iC˛ (_á icons in SrcOr mode (as in the ° d ONLN d.C <O ≥ (k ZMiniFinder). The Finder ° d ONLN dFC ≥O˛ )wAuses resources of type ICN# to draw icons on the desktop. Because ° d ONLN dàO <[b (w Z>the Finder uses ICN#s, it can draw icons in a variety of ways. ° d ONLN d«g <s O *An ° d ONLN d g Os˛ )PICN# resource is a list of 32 by 32 bit images that are grouped together. Common ° d ONLN ds < ˝ (õ Z'convention has been to group two 32 by ° d ONLN dBs ˝˛ )¡432 bit images together in each ICN#. The first image ° d ONLN dw <ã ¢ (ß Zis the actual icon, the ° d ONLN dè ¢ã˛ )fEsecond image is the mask for the icon. To get a handle to an ICN#, we ° d ONLN d’ã <ó à (≥ Z would use something like this:
° d ONLN dÙ£ <Æ P *TYPE ° d ONLN d˙≠ `∏ › +$
iListHndl = ^iListPtr; ° d ONLN d∑ `¬ Ï *
iListPtr = ^iListStruct; ° d ONLN d3¡ `Ã … *
iListStruct = record ° d ONLN dKÀ Ñ÷B +$
&icon : packed array[0..31] of Longint; ° d ONLN dt’ чB *
&mask : packed array[0..31] of Longint; ° d ONLN dúfl `Í ∫ ( ~End; {iListStruct} ° d ONLN dØÛ <˛ K ( ZVAR ° d ONLN d¥˝ ` ‚ +$
myILHndl : iListHndl; ° d ONLN dœ˝ w )ê {handle to an ICN#} ° d ONLN dÏ ` ” (. ~iBitMap : BitMap; ° d ONLN d w )ê {BitMap for the icon} ° d ONLN d! ` ” (8 ~mBitMap : BitMap; ° d ONLN d9 w )ê {BitMap for the mask} ° d ONLN dV% `0_ (L ~3MyILHndl:= iListHndl(GetResource('ICN#',iconID)); ° d ONLN dç/ `: *
#if MyILHndl = NIL then HandleError; ° d ONLN d¥9 ÑD= +$
%{and exit or whatever is appropriate}
° d ONLN d⁄O <[ (w Z,Once we have a handle to the icons, we need ° d ONLN dO[˛ )÷1to set up two bitMaps that we will be using later ° d ONLN d8\ <h H (Ñ Zin ° d ONLN d;[ Hg Ä ) CopyBits ° d ONLN dC\ Äh É )8:
° d ONLN dFt < P (õ Z ° d ONLN dKt `» )$HSetRect(icnRect,0,0,32,32); { define the icon's 'bounds'} ° d ONLN dï~ `â … *
With iBitMap do Begin ° d ONLN d´à <ì ı (Ø Z% baseAddr:= @MyILHndl^^.icon; ° d ONLN d“í <ù ™ *
rowbytes:= 4; ° d ONLN dÈí Ãù )ê ° d ONLN d˙í\ùù )ê
{ 4 * 8 =32} ° d ONLN dú <ß æ (√ Z bounds:= icnRect; ◊ X◊
*)
Drawing Icons (Ï1 ) of 4 ˇ ° ¿Ù%%DSIDICT:_cv
currentdict /bu known {bu}if
userdict /_cv known not{userdict /_cv 30 dict put}if
_cv begin
/bdf{bind def}bind def
currentscreen/cs exch def/ca exch def/cf exch def
/setcmykcolor where{/setcmykcolor get /cvcmyk exch def}{/cvcmyk{1 sub 4 1 roll 3{3 index add neg dup 0 lt{pop 0}if 3 1 roll}repeat setrgbcolor pop}bdf }ifelse
/ss{//cf //ca //cs setscreen}bdf
/stg{ss setgray}bdf
/strgb{ss setrgbcolor}bdf
/stcmyk{ss cvcmyk}bdf
/min1{dup 0 eq{pop 1}if}bdf
end
currentdict /bn known {bn}if
† ø t ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘ ,
Courier
° d ONLN d ( h * End; {with} ° d ONLN d ' 2 " *
° d ONLN d ' < 2 • )$With mBitMap do Begin ° d ONLN d * 1 < — ( X 6% baseAddr:= @MyILHndl^^.mask; ° d ONLN d P ; F Ü *
rowbytes:= 4; ° d ONLN d g E P ö *
bounds:= icnRect; ° d ONLN d Ç O Z " *
° d ONLN d Ö O < Z s )$ End; {with}
° d ONLN d ë e qq ( ç 6LIcons can represent desktop objects that are either selected or not. Folder ° d ONLN d › eq q⁄ ( çèand volume icons can ° d ONLN d Ú q }† ( ô 6Seither be open or not. The object (or the volume it is on) can either be online or ° d ONLN dE q† }⁄ ( ôæ offline. The ° d ONLN dR } âh ( • 6GFinder draws icons using all permutations of open, selected and online: †09 † Ç † é
IR ° d ONLN dö= I— *¿XDrawing icons as non-open is basically the same for online and offline volumes. We need ° d ONLN dÚ=—I⁄ (eÔto ° d ONLN dıI U∂ (q 6Xpunch a hole in the desktop for the icon. This is analogous to punching a hole in dough ° d ONLN dMI∂U⁄ (q‘with an ° d ONLN dUU aM (} 6Birregular shaped cookie-cutter. We can then sprinkle jimmies* all ° d ONLN dóUMa⁄ (}k over the cookie and they will ° d ONLN dµa m≈ (â 6Zonly stick in the area that we punched out (the mask). We do this by copyBitsing the mask ° d ONLN da≈m⁄ (â„onto ° d ONLN dm yö (ï 6Qthe desktop (whatever pattern) to our destRect. For non-open, non-selected icons: † Ç † é
ò ˝¿0 ò \ ( Ñ ` \ - Ñ `ò ˝¿0 ˘ ˘ ˘ ˘ ˘ ˘ ˘ ˇ˛˛ Ä ˛ Ä ˛ èˇÒ˛ ê ˛ ïU ˛ ê ˛ ïP ˛ ê ˛ ï ˛ ê ˛ ï ˛ ê ˛ ï@ ˛ ê ˛ ê ˛ èˇÒ˛ Ä ˛ Ä ˛ Ä ˛ Ä ˛ ÄÒ˛ Ä ˛ Ä ˛ Ä ˛ Ä ˛ ˇ˛˛ @ ˛ @ ˛ @ ˛ ˇ˛˛ ˘ ˘ † è † É
IR ° d ONLN dg≠ π *@5we use the SrcBic mode so that we punch a white hole:
° d ONLN dû≈ <– +$*SetRect(destRect,left,top,left+32,top+32); ° d ONLN d œ <⁄| *
° d ONLN d%˝ * ° d ONLN d'˝ <| )$@CopyBits(iBitMap,thePort^.portBits,icnRect,destRect,SrcXor,NIL);
° d ONLN dh ® (; 6 That’s all there is to drawing ° d ONLN dá ® ÷ )ê:an icon as non-open, non-selected. To draw the icon as non ° d ONLN d¡÷ ⁄ (;Ù- ° d ONLN d¬ + ^ (G 6open, selected: † Ç † é
IR ° d ONLN d 1 _ < k/ *51we need to do a little more work. We need to XOR ° d ONLN d b _/ k˛ )Û+a ltGray pattern into the boundsRect of the ° d ONLN d é k < w~ ( ì ZBicon. We will then punch the hole, draw the icon and then XOR out ° d ONLN d – k~ w˛ ( ìú the ltgray pattern that does ° d ONLN d Ì w < ÉÍ ( ü Z[not fall inside the mask. So, to draw the icon as offline, non-open, non-selected we would: ,
Courier
° d ONLN dJ è ` ö ƒ +$GetPenState(OldPen); ° d ONLN d` è öΩ )ê){save the pen state so we can restore it} ° d ONLN dã ô ` § ∞ ( ¿ ~PenMode(patXor); ° d ONLN dú £ < Æ F ( Z ° d ONLN dü £ ` Æ ´ )$PenPat(ltGray); ° d ONLN dØ ≠ < ∏ F ( ‘ Z ° d ONLN d≤ ≠ ` ∏ ƒ )$PaintRect(destRect); ° d ONLN d» ≠ ∏§ )ê${paint a ltGray background for icon} ° d ONLN dÌ ¡ < à F ( Ë Z ° d ONLN d ¡ ` û )$HCopyBits(mBitMap,thePort^.portBits,icnRect,destRect,SrcBic,NIL); {punch} ° d ONLN d9 À < ÷ A ( Ú Z ° d ONLN d; À ` ÷» )$HPaintRect(destRect);{XOR out bits outside of the mask, leaving the mask} ° d ONLN dâ ’ à ‡0 +l
{filled with ltGray} ° d ONLN d´ Í < ı A ( Z ° d ONLN d– Ù < ˇ§ *
HCopyBits(iBitMap,thePort^.portBits,icnRect,destRect,SrcOr,NIL);{ OR in } ° d ONLN dS ˛\ ‘ (%z{ the icon to the ltGray ° d ONLN dl < U (/ Zmask} ° d ONLN dr < Æ *
JSetPenState(OldPen); {restore the old pen state}
° d ONLN dΩ( <4 *0To draw the icon as offline, non-open, selected: † Ç † é
IR ° d ONLN dÓc <o ⁄ *; we would use a similar approach:
° d ONLN d{ <Ü P * ° d ONLN d{ `Ü ƒ )$GetPenState(OldPen); ° d ONLN d*{ ܬ )ê*{ save the pen state so we can restore it} ° d ONLN dVÖ `ê ∞ (¨ ~PenMode(patXor); ° d ONLN dhè `ö ´ *
PenPat(dkGray); ° d ONLN dyè ö« )ê+{ the icon is selected, so we need dkGray } ° d ONLN d•ô <§ F (¿ Z ° d ONLN d®ô `§ ƒ )$PaintRect(destRect); ° d ONLN dæô §Æ )ê&{ paint a dkGray background for icon } ° d ONLN dÊ≠ `∏ (‘ ~ {punch a hole in the background} ° d ONLN d∑ <¬ F (fi Z ° d ONLN d
∑ `¬† )$@CopyBits(mBitMap,thePort^.portBits,icnRect,destRect,SrcBic,NIL); ° d ONLN dLÀ `÷ ƒ *PaintRect(destRect); ° d ONLN dbÀ ÷¬ )ê*{XOR out bits outside of the mask, leaving ° d ONLN dí’ ‡Å *
the mask filled with dkGray} ° d ONLN d±È `Ù ( ~!{BIC the icon to the dkGray mask} ° d ONLN d‘Û `˛† *
@CopyBits(iBitMap,thePort^.portBits,icnRect,destRect,SrcBic,NIL); ° d ONLN d < F (. Z ° d ONLN d `x )$8SetPenState(OldPen); {restore the old pen state}
° d ONLN dQ <*ä (F ZCDrawing the opened icons requires one less step. We don’’t have to ° d ONLN dî ä)¬ (F®CopyBits ° d ONLN dú ¬*ÿ )8 the ° d ONLN d° ÿ*˛ )icon in, ° d ONLN d™* <6 ‚ (R Z!we just use the mask. Online and ° d ONLN dÀ* ‚6˛ )¶6offline icons are drawn the same way. To draw icons as ° d ONLN d6 <B Ç (^ Zopen, selected: † Ç † é
° d ONLN d ' < 2 ‹ +$! {punch a hole in the background} ° d ONLN d ! 1 < " ( X 6 ° d ONLN d $ 1 < <| )$@CopyBits(mBitMap,thePort^.portBits,icnRect,destRect,SrcBic,NIL); ° d ONLN d e E P " ( l 6 ° d ONLN d k E < P ™ )$PaintRect(destRect); ° d ONLN d Ç E Ã Pû )ê*{XOR out bits outside of the mask, leaving ° d ONLN d ≥ O Ã ZX *
the mask filled with dkGray} ° d ONLN d – Y d " ( Ä 6 ° d ONLN d ” Y < d † )$SetPenState(OldPen); ° d ONLN d È Y Ã dS )ê{restore the old pen state}
° d ONLN d o { » ( ó 6$To draw icons as open, non-selected: † Ç † é
ö ˜ ∫6 ò
f p Ü ∏ f s Ü ≤ ö ˜ ∫6 ˜ ˜ ˜ ˜ ˜ ˜ ˚ Ä˚ " ˚ ˝à˝ ˛" ˝ ˝à˝ ˛" ˝ ˝à˝ ˛" ˝ ˝à˝ ˛" ˝ ˝à˝ ˛" ˝ ˝à˝ ˛" ˝ ˝à˝ ˛" ˝ ˝à˝ ˛" ˝ ˝à˝ ˛" ˝ ˝à˝ ˛" ˝ ˝à˝ ˜ ˜ † è † É
IR ° d ONLN d* ß ≥h *8Ewe just need to change one line from above. Instead of XORing with a ° d ONLN do ßh ≥⁄ ( œÜdkGray pattern, we use ° d ONLN dÜ ≥ ø d ( € 6a ltGray pattern:
° d ONLN dò À ÷ " * ° d ONLN dõ À < ÷ á )$PenPat(ltGray); ° d ONLN d¨ À Ã ÷ô )ê){icon is non-selected, so we need ltGray}
° d ONLN d÷ · Ì “ ( 6"These techniques will work on any ° d ONLN d¯ · “ Ì⁄ )∫0background, window-white or desktop-gray and all ° d ONLN d) Ì ˘ ™ ( 6 patterns in between. Have fun. ° d ONLN dH ! *$* ° d ONLN dJ ! I ) jimmies ° d ONLN dR I ≥ )(: little bits of chocolate ° d ONLN dmA M Ç (i 6Further Reference: l 4l˘ ° d ONLN dÄN *Z . +
• ° d ONLN dÇN <Z r ) QuickDraw ° d ONLN dåZ *f . (Ç H• ° d ONLN déZ <f å )Toolbox Utilities ◊ 4◊˘
(Ï 64 ) of 4 (Ïæ
Drawing Icons ˇd ◊# ˇ ˇˇˇˇ # ◊ ° d WORD S † å ° d WORD R… † Ç
/ Z Å#
0Ià:µú9 " { ˇˇˇˇˇˇˇˇ # † ƒ ° d
ONLN f ˛ † å ° d 1drw2 … -·_ Ä ˇˇˇˇˇˇ è ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˙ ó@ † ò , Times
. eRSeRS +]BNew Technical Notes † ô ° d drw2 : °„ † ó ° d 1drw2 eÙ Ä ˇˇˇˇˇˇ P ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä E¿ † ò
Ä ( {ïDeveloper Support † ô ° d drw2 : °„ † ó ° d `drw2 - Ô ˇˇˇˇˇˇ K Ô - Z f f Z ° d 1drw2 ¿˙È ˇˇˇˇˇˇ K ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : 0 ° ö ˇÙ Ä † ò
0 ( UÔ † ô ° d drw2 : °„ † ó ° d 1drw2 ÔÊ˙ ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˝Ä † ò
l +& ® † ô ° d drw2 : °„ † ó ° d 1drw2  -¯ y ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä % † ò
BÄ ( Z \ Macintosh † ô ° d drw2 : °„ † ó † ç ° d drw2 D † É ° d WORD † ç
IR . ° d ONLN d { < éO ( ® Z Drawing Icons the System 7 Way
° d ONLN d ç < ú r *Imaging ° d ONLN d ' ç~ ú˛ ( ∏úM.IM.IconDrawing
° d ONLN d 8 ® < ¥ t ( – Z Revised by: ° d ONLN d D ® Ñ ¥* )H Don Moccia and C.K. Haun <TR> ° d ONLN d b ®æ ¥˛ ( –‹ October 1992 ° d ONLN d o ¥ < ¿ q ( ‹ Z Written by: ° d ONLN d { ¥ Ñ ¿ )H Jim Mensch and David Collins ° d ONLN d ò ¥æ ¿˛ ( ‹‹ October 1991 ° d ONLN d • à < ÿO ( Ù Z:This Technical Note describes how to utilize the built-in ° d ONLN d fl ÃO ÿ˛ ( Ùm"System 7 icon drawing utility. Use ° d ONLN d ÿ < ‰ò ( ZJthis information to better conform to the System 7 visual human interface. ° d ONLN dM < ¸ – *Changes since May 1992: ° d ONLN dd – ¸‘ )î6 In this Note, we replaced the C and Pascal interface ° d ONLN dö ‘ ¸˛ (Ú files and ° d ONLN d§ ¸ <Ω ($ ZOcorrected the related text. So much text was tweaked that change bars are used ° d ONLN dÛ ¸Ω˛ ($€ only on code ° d ONLN d < f (0 Zchanges. ? X?
° d ONLN dBÒ < | *'The New ° d ONLN dJÚ | † )@'ic' ° d ONLN dNÒ †
)$ Type Resources
° d ONLN d^ < Ç (5 Z
PlotIconID ° d ONLN dh
Ç ô )F and ° d ONLN dm ô )PlotCIconHandle ° d ONLN d|
~ )i allow the use of standard ° d ONLN dó ~® )|CIcons ° d ONLN dù
®∏ )* as ° d ONLN d°
∏˛ )
documented in ° d ONLN dØ <& ê (B ZInside Macintosh ° d ONLN d¿ ê& ‹ )TVolume V. The ° d ONLN dŒ ‹%" )L
PlotIconID ° d ONLN dÿ"&8 )F call ° d ONLN dfi8&˛ ))also permits the use of a new set of icon ° d ONLN d& <2 ¥ (N Zresources documented in ° d ONLN d & ¥2 )xInside Macintosh ° d ONLN d1&2C )T Volume VI, ° d ONLN d<&C2˛ );'Chapter 9. This new set is a collection ° d ONLN dd2 <>‡ (Z Z[of different icons, representing a single Finder object, into a family. Each member of the ° d ONLN dø2‡>˛ (Z˛family ° d ONLN dΔ? <K · (g Z has the same resource ID as the ° d ONLN dÊ> ·J )•'ICN#' ° d ONLN dÏ? K* )*, and ° d ONLN dÚ?*K˛ ) +a resource type indicating the icon data it ° d ONLN d K <Wª (s ZPcontains. Currently Apple has defined three sizes of icons and three bit depths ° d ONLN dnKªW˛ (sŸfor each size. ° d ONLN d}W <cb ( Z@The sizes are large (32 by 32 pixels), small (16 by 16 pixels), ° d ONLN dΩWbc˛ (Ä and mini (12 by 12 pixels). The ° d ONLN d›c <ow (ã ZEbit depths are 1, 4, and 8. The actual resource types are defined as:
° d ONLN d#{ <Ü Õ * Large1BitMask = 'ICN#'; ° d ONLN dAÖ <ê Õ *
Large4BitData = 'icl4'; ° d ONLN d_è <ö Õ *
Large8BitData = 'icl8'; ° d ONLN d}ô <§ Õ *
Small1BitMask = 'ics#'; ° d ONLN dõ£ <Æ Õ *
Small4BitData = 'ics4'; ◊ X◊
*" Drawing Icons the System 7 Way (Ïˇ1 , Palatino
)
)of 12 ˇ ° ¿Ù%%DSIDICT:_cv
currentdict /bu known {bu}if
userdict /_cv known not{userdict /_cv 30 dict put}if
_cv begin
/bdf{bind def}bind def
currentscreen/cs exch def/ca exch def/cf exch def
/setcmykcolor where{/setcmykcolor get /cvcmyk exch def}{/cvcmyk{1 sub 4 1 roll 3{3 index add neg dup 0 lt{pop 0}if 3 1 roll}repeat setrgbcolor pop}bdf }ifelse
° d ONLN d x Q ]£ *RThe 1-bit-per-pixel member of each size also contains the mask data for all icons ° d ONLN d Q£ ]⁄ ( y¡ of that size ° d ONLN d ◊ ] i] ( Ö 6E(yes, this means that all your icons of a certain size must have the ° d ONLN d ]] i÷ ( Ö{same mask). A 1-bit-per ° d ONLN d3 ]÷ i⁄ )y- ° d ONLN d4 j v ] ( í 6
pixel member ° d ONLN dA j ] v )E#must exist for each icon size that ° d ONLN dd i uM )™
PlotIconID ° d ONLN dn jM v⁄ )F uses. The icon size used is ° d ONLN dã v Ç∂ ( û 6]determined by the size of the destination rectangle. If the destination rectangle is greater ° d ONLN dË v∂ Ç⁄ ( û‘than 16 ° d ONLN d Ç é ( ™ 6:pixels on a side then the large icon will be used. If the ° d ONLN d* Ç é⁄ ( ™7(rectangle is 13–16 pixels on both sides, ° d ONLN dS é ö ( ∂ 6)the small icon will be used. If it is 12 ° d ONLN d| é ö⁄ )≤9or less on each side, the mini-icon will be used. The bit ° d ONLN d∂ ö ¶ à ( ¬ 6%depth is determined by the device of ° d ONLN d€ ö à ¶⁄ )¥6the grafPort you plot into at drawing time. Be sure to ° d ONLN d ¶ ≤& ( Œ 69create a color grafPort when you want to use color icons.
° d ONLN dL Ÿ *'$Icon Families (or Suites and Caches ° d ONLN dp Ÿ⁄ ( ı;As the Tool Set Refers to ° d ONLN dä Ÿ Ë C ( 6Them)
° d ONLN dê Ù @ *An icon ° d ONLN dò Ù @ ⁄ )(Vfamily is simply a collection of icon handles that contain up to one image of each bit ° d ONLN dÔ q (( 6Jdepth and size for a given icon. The family can be fully populated (every ° d ONLN d9 q ⁄ ((èpossible size or depth ° d ONLN dP e (4 6available), or it ° d ONLN db e⁄ )MJcan have only those icons that exist or are needed. By using families, you ° d ONLN d≠ $T (@ 6@remove the need to determine which size or depth of icon to use ° d ONLN dÌT$⁄ (@rwhen drawing into a given ° d ONLN d$ 0Δ (L 6Vrectangle. Several system routines, the Notification Manager for example, can take an ° d ONLN d]$Δ0⁄ (L‰icon ° d ONLN db0 <> (X 6;family handle when an icon is requested. This permits them ° d ONLN dù0><⁄ (X\ to use the proper color icons if ° d ONLN dæ< H≠ (d 6Xavailable. In the case of a sparsely populated icon family, when the proper icon is not ° d ONLN d<≠H⁄ (dÀ
available, ° d ONLN d!H TD (p 6Dthe icon toolkit will pick a substitute to produce the best results. ° d ONLN dfa m Í **An icon cache is a family that also has a ° d ONLN dê` Íl )“ProcPtr ° d ONLN dóam )1 ° d ONLN dòa mB )and a ° d ONLN dû`Bll )"refCon ° d ONLN d§alm⁄ )*. The main difference ° d ONLN d∫m y J (ï 6
° d ONLN d'™ µ — *%FUNCTION IconGetter(theType: ResType; ° d ONLN dM¥ ø ˛ *
. yourDataPtr: Ptr): Handle;
° d ONLN d| ÷ *7This function should return either the icon data to be ° d ONLN d≥ ÷⁄ )˘*drawn or NIL to signify that this entry in ° d ONLN dfi÷ ‚ @ (˛ 6 the icon ° d ONLN dÁ÷ @‚⁄ )(Ucache does not exist. Icon caches can be used with all icon family calls. A few extra ° d ONLN d =‚ Ó ˇ (
63calls are also available to manipulate icon caches.
° d ONLN d q Ê *'Drawing Modes or Transforms
° d ONLN d ç! - ` *In addition to ° d ONLN d ú! `-⁄ )HHvarious sizes and bit depths, icons can be drawn with different modes or ° d ONLN d Â- 9 å (U 6transforms. Transforms ° d ONLN d ¸- å9⁄ )tFare analogous to certain Finder states for the icons. For example, the ° d ONLN d
C: F › (b 6(transform that you would use to show an ° d ONLN d
k: ›Fó )≈(icon of a disk that has been ejected is ° d ONLN d
ì9óE÷ )∫ ttOffline ° d ONLN d
ú:÷F⁄ )?. ° d ONLN d
ûF R ÷ (n 6+Here is a list of the available transforms: ◊ 4◊˘
*~2 ) of 12 (Ïq Drawing Icons the System 7 Way ˇ‹ ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +Z-Developer Support Center ( -Ê October 1992 / X / ,
Courier
° d ONLN d ) < 4 “ ( P Z ttNone = $0; ° d ONLN d 3 < > “ *
ttDisabled = $1; ° d ONLN d > = < H “ *
ttOffline = $2; ° d ONLN d ] G < R “ *
ttOpen = $3; ° d ONLN d | Q < \ · *
!ttSelected = $4000; ° d ONLN d û [ < fE *
5ttSelectedDisabled = (ttSelected + ttDisabled); ° d ONLN d ‘ e < p@ *
4ttSelectedOffline = (ttSelected + ttOffline); ° d ONLN d o < z1 *
ttSelected ° d ONLN dx ™ ı ∂{ )F transform can be added to ° d ONLN dì ™{ ∂˛ )Üany of the other transform ° d ONLN dÆ ∂ < ¬ Y ( fi Ztypes. ° d ONLN dµ Œ < ⁄´ *NThere are also transforms that use the Finder label colors to color the icon. ° d ONLN d Œ´ ⁄˛ ( ˆ…To determine the ° d ONLN d € < Á ( Z3proper label for a file’s icon, you can check bits ° d ONLN dG € ÁV )‰ 1–3 of the ° d ONLN dR ⁄V Êá )6fdFlags ° d ONLN dY €á Á˛ )1 field in the file’s Finder ° d ONLN du Á < Û ( Zinfo. (See the ° d ONLN dÑ Á Û )C Finder Interface chapter in ° d ONLN d† Á ÛT )ÉInside Macintosh ° d ONLN d∞ ÁT Û˛ )R! Volume VI for more information). ° d ONLN d“ Ù < ê ( ZFThese bits contain a number from 0 to 7. Simply add the corresponding ° d ONLN d Ûê ˇ» ( ÆttLabel ° d ONLN d Ù» )8 value to ° d ONLN d) Ù ˛ )(the ° d ONLN d- < É (( ZItransform that you give the call. The label values are defined like this:
° d ONLN dw <# Ø *ttLabel1 = $0100; ° d ONLN dè" <- Ø *
/atBottomLeft = (atBottom + atLeft); ° d ONLN d ] <h “ *
atRight = $C; ° d ONLN d 3g <rT *
8atCenterRight = (atVerticalCenter + atRight); ° d ONLN d lq <| *
-atTopRight = (atTop + atRight); ° d ONLN d ö{ <Ü, *
0atBottomRight = (atBottom + atRight); ◊ X◊
*J Drawing Icons the System 7 Way (Ïˇ3 ) of 12 ˇH ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘
° d ONLN d ) 8ë *'5And Now (Drum Roll Please) the Calls and What to Pass
° d ONLN d 6 D PJ *<Now that we have defined every major data type we can think ° d ONLN d r DJ P⁄ ( lh of, here are the actual toolkit ° d ONLN d í Q ] ˚ ( y 60calls themselves. One word of caution: only the ,
Courier ° d ONLN d ¬ P ˚ \V )„
ForEachIconDo ° d ONLN d œ QV ]î )[ call protects ° d ONLN d fi Qî ]⁄ )>the handle that ° d ONLN d Ó ] i- ( Ö 6:is passed to it, so make your icon resources nonpurgeable. ° d ONLN d) u Å } *Icon Family Calls
° d ONLN ds £ Ø l * NewIconSuite ° d ONLN d § l ∞£ )TA returns an empty icon family handle with all members set to NIL.
° d ONLN d¡ º « Ù ( „ 6,FUNCTION AddIconToSuite(theIconData: Handle; ° d ONLN dÓ Δ — Â *
) theSuite: Handle; ° d ONLN d – €
*
1 theType: ResType): OSErr;
° d ONLN dJ Á Û ¥ * This call will add the data in ° d ONLN di Ê ¥ Ú )ú theIconData ° d ONLN dt Á Ûq )M into the suite at the ° d ONLN dã Áq Û⁄ )plocation reserved for ° d ONLN d° Û ˇ I ( 6theType ° d ONLN d® Ù I í )1 of icon data. ° d ONLN d∑ Û í ˇ Ù )IAddIconToSuite ° d ONLN d≈ Ù Ù ` )b will replace any old ° d ONLN d€ Ù` ⁄ )ldata in that slot without ° d ONLN dı
fl () 6)disposing of it, so you may want to call ° d ONLN d fl O )«GetIconFromSuite ° d ONLN d.O
⁄ )p to obtain the old handle (if ° d ONLN dL B (6 6Bany) to dispose of it. This call will be used most often with the ° d ONLN dé
Bñ (6` NewIconSuite ° d ONLN döñ⁄ )T call to fill the ° d ONLN d¨ & ® (B 6 empty family after it’s created.
° d ONLN dÕ2 = *2FUNCTION GetIconFromSuite(VAR theIconData: Handle; ° d ONLN d < G Ô *
specified by ° d ONLN døi u I (í 6theType ° d ONLN dΔj Iv ú )1. If you intend to ° d ONLN dŸj úvV )S(dispose of this handle, be sure to call ° d ONLN diVu∏ )∫AddIconToSuite ° d ONLN dj∏v⁄ )b with a ° d ONLN dv Ç ‘ (û 6(NIL handle to zero out the family entry.
° d ONLN d@é ô ‡ *(FUNCTION ForEachIconDo(theSuite: Handle; ° d ONLN diò £ *
3 selector: IconSelectorValue; ° d ONLN dù¢ ≠ Í *
* action: IconAction; ° d ONLN d»¨ ∑ *
0 yourDataPtr: Ptr): OSErr;
° d ONLN d˘√ œ ö * This routine will call your ° d ONLN d¬ öŒ ‡ )Ç
IconAction ° d ONLN d √ ‡œ )F procedure ° d ONLN d*√œ⁄ )7'(see below) for each icon in the family ° d ONLN dR– ‹ V (¯ 6
specified by ° d ONLN d_œ V€ é )>selector ° d ONLN dg– é‹ í )8 ° d ONLN dh– í‹ ® )and ° d ONLN dlœ ®€ ‡ )theSuite ° d ONLN dt– ‡‹ )8. The ° d ONLN dzœ €8 ) selector ° d ONLN dÇ–8‹⁄ )8# parameter is a bit-level flag that ° d ONLN d¶‹ Ë ≥ ( 6 specifies which family members ° d ONLN d≈‹ ≥Ë⁄ )õ=to operate on; they can be added together to create composite ° d ONLN dË Ù§ ( 6Uselectors that work on several different family members. The values for selector are:
° d ONLN dY ¬ *"svLarge1Bit = $00000001; ° d ONLN d|
¬ *
"svLarge4Bit = $00000002; ° d ONLN dü ¬ *
"svLarge8Bit = $00000004; ° d ONLN d¬ ) ¬ *
"svSmall1Bit = $00000100; ° d ONLN dÂ( 3 ¬ *
"svSmall4Bit = $00000200; ° d ONLN d2 = ¬ *
"svSmall8Bit = $00000400; ° d ONLN d+< G ¬ *
"svMini1Bit = $00010000; ° d ONLN dNF Q ¬ *
"svMini4Bit = $00020000; ° d ONLN dqP [ ¬ *
"svMini8Bit = $00040000; ° d ONLN dîZ e ¬ *
"svAllLargeData = $000000FF; ° d ONLN d∑d o ¬ *
"svAllSmallData = $0000FF00; ° d ONLN d⁄n y ¬ *
"svAllMiniData = $00FF0000; ° d ONLN d˝x É] *
AsvAll1BitData = (svLarge1Bit + svSmall1Bit + svMini1Bit); ° d ONLN d ?Ç ç] *
AsvAll4BitData = (svLarge4Bit + svSmall4Bit + svMini4Bit); ° d ONLN d Åå ó] *
AsvAll8BitData = (svLarge8Bit + svSmall8Bit + svMini8Bit); ° d ONLN d √ñ ° ¬ *
"svAllAvailableD = $FFFFFFFF; ◊ 4◊˘
*/4 ) of 12 (Ïq Drawing Icons the System 7 Way ˇö ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +Z-Developer Support Center ( -Ê October 1992 / X /
° d ONLN d < ) ˚ ( E Z*The action procedure that gets called for ° d ONLN d * ˚ )˛ )ø7each icon type selected for the family is a Pascal type ° d ONLN d b ) < 5 Î ( Q Z&function with the following interface: ,
Courier
° d ONLN d â A < L ı *%FUNCTION IconAction(theType: ResType; ° d ONLN d Ø K < V *
( VAR theIcon: Handle; ° d ONLN d ÿ U < ` *
- yourDataPtr: Ptr): OSErr;
° d ONLN d l < x Ü *The parameter ° d ONLN d k Ü w ∑ )JtheIcon ° d ONLN d l ∑ xX )1 is passed by reference here so ° d ONLN d; lX x˛ )° that your routine can modify the ° d ONLN d\ y < Ö ‚ ( ° Z$contents of the suite directly. The ° d ONLN dÄ x ‚ Ñ7 )¶ yourDataPtr ° d ONLN då y7 Ö˛ )U¶meter is the value passed when you ° d ONLN d≥ Ü < í \ ( Æ Zcalled ° d ONLN d∫ Ö \ ë ∑ )
ForEachIconDo ° d ONLN d« Ü ∑ íx )[&. It allows you to easily communicate ° d ONLN dÌ Üx í˛ )¡with your application. The ° d ONLN d ì < ü ◊ ( ª Z action procedure returns an ° d ONLN d$ í ◊ û ˙ )õOSErr ° d ONLN d) ì ˙ üT )#. If any value ° d ONLN d8 ìT üî )Z other than ° d ONLN dC íî û∑ )@noErr ° d ONLN dH ì∑ ü˛ )#
° d ONLN d3 – < €' */FUNCTION GetIconSuite(VAR theIconSuite: Handle; ° d ONLN dc ⁄ < Â *
( theResID: INTEGER; ° d ONLN då ‰ < Ô^ *
: selector: IconSelectorValue): OSErr;
° d ONLN d« ˙ < ê * GetIconSuite ° d ONLN d” ˚ ê ¸ )T will create a new icon ° d ONLN dÎ ˚ ¸˛ )l7family and fill it from the current resource chain with ° d ONLN d# < µ (0 Zthe icons of resource ID ° d ONLN d< µ Ì )ytheResID ° d ONLN dD Ìa )8 and types indicated by ° d ONLN d\aô )tselector ° d ONLN ddôÏ )8. This is the call ° d ONLN dwÏ˛ )Syou ° d ONLN d{ <!á (= ZHwill probably use most often to create an icon family. Note that if you ° d ONLN d√á ˛ (=•SetResLoad(False) ° d ONLN d’! <-Ø (I ZQbefore making this call, the suite will be filled with unloaded resource handles.
° d ONLN d'9 <D ı *%FUNCTION PlotIconSuite(theRect: Rect; ° d ONLN dMC <N, *
0 align: IconAlignmentType; ° d ONLN d~M <X@ *
4 transform: IconTransformType; ° d ONLN d≥W <b@ *
4 theIconSuite: Handle): OSErr;
° d ONLN dËm <y *]This call renders the proper icon image from the passed icon family based on the bit depth of ° d ONLN dGy <Ö œ * the display you are using and ° d ONLN dey œÖ˛ )ì<the rectangle that you have passed. The parameters align and ° d ONLN d¢Ö <ë (≠ ZYtransform are applied to the icon selected for drawing and then the icon is plotted into ° d ONLN d˚Öë˛ (≠the ° d ONLN dˇí <û í (∫ Zcurrent grafPort. ° d ONLN dë íù Ì )V
PlotIconSuite ° d ONLN d í Ìûj )[ chooses the appropriate ° d ONLN d7íjû˛ )} icon based primarily on size. ° d ONLN dUû <™ Y (Δ ZOnce ° d ONLN dZû Y™˛ ) Tthe proper icon size is determined (based on the destination rectangle), the present ° d ONLN dØ™ <∂ì (“ ZKmember of that size with the deepest bit depth that the current device can ° d ONLN d˙™ì∂˛ (“±use is selected. A size ° d ONLN d∑ <√ z (fl Z category is ° d ONLN d ∑ z√– )>>considered present if the black-and-white member (with mask), ° d ONLN d\∂–¬˙ (flÓ'ICN#' ° d ONLN db∑˙√˛ )*, ° d ONLN dd√ <œ f (Ï Z'ics#' ° d ONLN djƒ f– Ñ )*, or ° d ONLN do√ Ñœ Æ ) 'icm#' ° d ONLN duƒ Æ– )*, is ° d ONLN dzƒ – ˘ ) present. ° d ONLN dÉ√ ˘œT )/
PlotIconSuite ° d ONLN dêƒT–˛ )[ can be used for both picture ° d ONLN dÆ– <‹ ∫ (¯ Zaccumulation and printing.
° d ONLN d…Ë <Û' */FUNCTION DisposeIconSuite(theIconSuite: Handle; ° d ONLN d˘Ú <˝O *
7 disposeData: BOOLEAN): OSErr;
° d ONLN d 1 < ì *This call disposes ° d ONLN d D ìh )W/the icon family handle itself. In addition, if ° d ONLN d shµ )’ disposeData ° d ONLN d ~ µ˛ )M is true, any of ° d ONLN d è <!∂ (= ZRthe icon data handles that do not belong to a resource fork will also be disposed.
° d ONLN d ‚- <8ã *CFUNCTION SetSuiteLabel(theSuite: Handle; theLabel: INTEGER): OSErr;
° d ONLN d
&C <Oª *TThis call allows you to specify a label to draw an icon of this suite when no label ° d ONLN d
zCªO˛ (kŸis specified in ° d ONLN d
äO <[ ó (x Z
PlotIconSuite ° d ONLN d
óP ó\∑ )[=. This is used primarily to ensure that a family passed to a ° d ONLN d
‘P∑\˛ (x’system routine ° d ONLN d
„\ <h s (Ñ Z gets drawn ° d ONLN d
Ó\ sh˛ )7Swith the proper label. The default label can be overridden by specifying a label in ° d ONLN d Bh <t ó (ë Z
PlotIconSuite ° d ONLN d Oi óu õ )[.
° d ONLN d QÅ <å6 (® Z2FUNCTION GetSuiteLabel(theSuite: Handle): INTEGER;
° d ONLN d Ñó <£ ó *
GetSuiteLabel ° d ONLN d ëò ó§E )[' returns the label previously set with ° d ONLN d ∏óE£† )Æ
SetSuiteLabel ° d ONLN d ≈ò†§§ )[. ◊ X◊
(Ï Z Drawing Icons the System 7 Way (Ïˇ5 ) of 12 ˇÃ ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘
° d ONLN d ) 5 x *$Icon Cache Calls ° d ONLN d A Mu *NIn addition to the icon family calls, icon caches have these additional calls: ,
Courier
° d ONLN d a Y d ˘ *-FUNCTION MakeIconCache(VAR theHandle: Handle; ° d ONLN d è c n Ù *
, makeIcon: IconGetter; ° d ONLN d º m x! *
5 yourDataPtr: UNIV Ptr): OSErr;
° d ONLN d Ú Ñ ê ˜ *1This call creates an empty icon cache similar to ° d ONLN d# É ˜ èK )fl NewIconSuite ° d ONLN d/ ÑK êR )T, ° d ONLN d1 ÑR ê⁄ ) and associates the additional ° d ONLN dO ê ú ( ∏ 66icon loading procedure and data value with the family.
° d ONLN dÜ ® ≥ — *%FUNCTION LoadIconCache(theRect: Rect; ° d ONLN d¨ ≤ Ω *
0 align: IconAlignmentType; ° d ONLN d› º « *
4 transform: IconTransformType; ° d ONLN d Δ — *
4 theIconCache: Handle): OSErr;
° d ONLN dG ‹ Ë ê *This call allows preflight ° d ONLN db ‹ ê Ë⁄ )xDloading of certain elements of your icon cache. This is handy if you ° d ONLN dß Ë Ù
( 62suspect that certain drawing operations may occur ° d ONLN dŸ Ë
Ù⁄ )ı)at a time not convenient for loading your ° d ONLN d ı c ( 6Ficon data (e.g., when your resource fork might not be in open chain). ° d ONLN dI Ùc æ ( Å
LoadIconCache ° d ONLN dV ıæ⁄ )[ takes ° d ONLN d] á (* 6the same parameters as ° d ONLN dt á
‚ )o
PlotIconSuite ° d ONLN dÅ ‚` )[ and uses the same criteria ° d ONLN dù`⁄ )~to select the icon to load. ° d ONLN dπ Y (6 6
The grafPort ° d ONLN dΔ Y⁄ )APmust be set properly before making this call since it is one of the criteria for ° d ONLN d & ü (B 6 determining the icon to load. ° d ONLN d53 ? — *&The following four calls are provided ° d ONLN d[3 —? )π
to change ° d ONLN de2>6 )4theData ° d ONLN dl36?J )1 or ° d ONLN dp2J>{ )theProc ° d ONLN dw3{?⁄ )1 associated with an ° d ONLN dã? K L (g 6 icon cache:
° d ONLN dóW b Ô *+FUNCTION GetIconCacheData(theCache: Handle; ° d ONLN dƒa l *
3 VAR theData: Ptr): OSErr; ° d ONLN d¯k v Ô *
+FUNCTION SetIconCacheData(theCache: Handle; ° d ONLN d%u Ä *
/ theData: Ptr): OSErr; ° d ONLN dU ä Ô *
+FUNCTION GetIconCacheProc(theCache: Handle; ° d ONLN dÇâ î: *
: VAR theProc: IconGetter): OSErr; ° d ONLN dΩì û Ô *
+FUNCTION SetIconCacheProc(theCache: Handle; ° d ONLN dÍù ®& *
6 theProc: IconGetter): OSErr;
° d ONLN d!≥ ø ◊ *"Plotting Icons Not Part of a Suite ° d ONLN dDÀ ◊ *5The next calls are grouped because they are similar. ° d ONLN dyÀ◊⁄ )ˇ'They let you plot an icon to the screen ° d ONLN d°ÿ ‰m ( 6Fwithout your creating an icon suite. They are also good if you have a ° d ONLN dÁ◊m„ó ( ã'cicn' ° d ONLN dÌÿó‰¿ )* instead ° d ONLN dˆÿ¿‰⁄ ))of an ° d ONLN d¸‰ Q ( 6 icon family.
° d ONLN d ¸ ¬ *"FUNCTION PlotIconID(theRect: Rect; ° d ONLN d, ˘ *
- align: IconAlignmentType; ° d ONLN dZ
*
1 transform: IconTransformType; ° d ONLN då % ˛ *
. theResID: INTEGER): OSErr; ° d ONLN dª. 9 € *'FUNCTION PlotCIconHandle(theRect: Rect; ° d ONLN d„8 C *
2 align: IconAlignmentType; ° d ONLN dB M& *
6 transform: IconTransformType; ° d ONLN dML W+ *
7 theCIcon: CIconHandle): OSErr; ° d ONLN dÖ` k ÷ *&FUNCTION PlotIconMethod(theRect: Rect; ° d ONLN d¨j u
*
1 align: IconAlignmentType; ° d ONLN dfit ! *
5 transform: IconTransformType; ° d ONLN d ~ â ˛ *
. theMethod: IconGetter; ° d ONLN d Cà ì& *
6 yourDataPtr: UNIV Ptr): OSErr; ◊ 4◊˘
*=6 ) of 12 (Ïq Drawing Icons the System 7 Way ˇ ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +Z-Developer Support Center ( -Ê October 1992 / X / ,
Courier
° d ONLN d ' < 2 ˙ ( N Z&FUNCTION PlotIconHandle(theRect: Rect; ° d ONLN d ' 1 < <1 *
1 align: IconAlignmentType; ° d ONLN d Y ; < FE *
5 transform: IconTransformType; ° d ONLN d è E < P, *
0 theIcon: Handle): OSErr; ° d ONLN d ¿ Y < d ˙ *&FUNCTION PlotSICNHandle(theRect: Rect; ° d ONLN d Á c < n1 *
1 align: IconAlignmentType; ° d ONLN d m < xE *
5 transform: IconTransformType; ° d ONLN dO w < Ç, *
0 theSICN: Handle): OSErr;
° d ONLN dÄ é < ö j *
All these ° d ONLN dä é j ö4 ).)routines share the following parameters: ° d ONLN d≥ ç4 ôn ) theRect ° d ONLN dª én ö˛ ): is the destination rectangle to ° d ONLN d€ õ < ß ƒ ( √ Z draw the indicated icon into; ° d ONLN d˘ ö ƒ ¶ Á )àalign ° d ONLN d˛ õ Á ß )# is the ° d ONLN d õ ߲ ) 4alignment method to use if the icon does not fit the ° d ONLN d; ® < ¥ â ( – Zrectangle given; ° d ONLN dL ß â ≥ » )M transform ° d ONLN dU ® » ¥€ )?< indicates the desired appearance of the icon on the screen. ° d ONLN dí ¡ < Õ J ( È ZIn ° d ONLN dï ¿ J à ê )
PlotIconID ° d ONLN dü ¡ ê Õ ‹ )F, the parameter ° d ONLN dØ ¿ ‹ Ã )LtheResID ° d ONLN d∑ ¡ Õ$ )8 is ° d ONLN dª ¡$ Õ… )!the resource ID of the family of ° d ONLN d‹ ¿… ÃÂ )•'ic' ° d ONLN d‡ ¡Â Õ˛ ) type ° d ONLN dÊ Õ < Ÿ l ( ı Z
resources ° d ONLN d Õ l Ÿ˛ )0Yto use. If the correct bit depth or the size required is not defined, the closest-fitting ° d ONLN dJ Ÿ <  ç ( Zone will be used. ° d ONLN d\ Ú < ˛ T *The ° d ONLN d` Ò T ˝ Ω )PlotCIconHandle ° d ONLN do Ú Ω ˛ ˜ )i parameter ° d ONLN dz Ò ˜ ˝/ ):theCIcon ° d ONLN dÇ Ú/ ˛N )8 is a ° d ONLN dà ÚN ˛˛ ) !handle that you get to a standard ° d ONLN d™ ˇ < Œ (' Z QuickDraw color icon. Unlike ° d ONLN d« ˛ Œ
)í PlotCIcon ° d ONLN d– ˇ
)?, ° d ONLN d“ ˛
} )PlotCIconHandle ° d ONLN d· ˇ} ´ )i
does not ° d ONLN dÎ ˇ´ ˛ ).honor the current ° d ONLN d˝ < ˝ (4 Z'foreground and background colors. Call ° d ONLN d$ ˝5 )¡GetCIcon ° d ONLN d, 5˛ )8) to load the icon. Dispose of it when you ° d ONLN dV <$> (@ Z7are done, since they can take up quite a bit of memory. ° d ONLN dé0 << û *PlotIconMethod ° d ONLN dú1 û= ’ )b calls your ° d ONLN d®0 ’< )7
IconGetter ° d ONLN d≤1=V )F procedure, ° d ONLN dæ1V=˛ );#discussed earlier, to check for the ° d ONLN d‚= <I • (e Zexistence of icon data. ° d ONLN d˚U <a û *PlotIconHandle ° d ONLN d V ûb )b will plot the data from ° d ONLN d"V b )nan ° d ONLN d%UaE )'ICN#' ° d ONLN d+VEbW )* or ° d ONLN d/UWaÅ )'ICON' ° d ONLN d5VÅb˛ )* resource from its handle. ° d ONLN dPc <o £ (ã ZIt is a new version of ° d ONLN dgb £n € )gPlotIcon ° d ONLN doc €o fl )8. ° d ONLN dq{ <á û (§ ZPlotSICNHandle ° d ONLN d| ûà )b plots the data of a ° d ONLN dî{á- )e'SICN' ° d ONLN dö|-à2 )* ° d ONLN dõ|2à‘ ) resource from its handle. Only ° d ONLN d∫{‘Რ)¢'SICN' ° d ONLN d¡à <î¡ (∞ ZLresources with a single member, or one in which the second member is a mask ° d ONLN d
à¡î˛ (∞flfor the first, ° d ONLN d î <† ì (º Zwill plot correctly. ° d ONLN d1¨ <∏; *9All the functions return an error code if things did not ° d ONLN dj¨;∏˛ )ˇ(go well with the drawing or, in the case ° d ONLN dìπ <≈ Z (· Zof the ° d ONLN dö∏ Zƒ † )
PlotIconID ° d ONLN d§π †≈ë )F6 call, if the indicated icon family could not be used. ° d ONLN d€— <› ≠ (˘ ZMiscellaneous Calls
° d ONLN dÔÈ <Ù ˇ *'FUNCTION GetLabel(labelNumber: INTEGER; ° d ONLN dÛ <˛ *
+ VAR labelColor: RGBColor; ° d ONLN dC˝ <6 *
2 VAR labelString: Str255): OSErr;
° d ONLN dv < = *:This call returns the actual color and string used in the ° d ONLN d∞= ˛ (;[(label menu of the Finder and the label’s ° d ONLN dŸ <+ (G Z,Control Panel. This information is provided ° d ONLN d +˛ )“3in case you wish to include the label text or color ° d ONLN d9+ <7# (S Z2when displaying a file’s icon in your application.
° d ONLN dlC <N **FUNCTION IconSuiteToRgn(theRgn: RgnHandle; ° d ONLN dóM <X ˇ *
' iconRect: Rect; ° d ONLN døW <b1 *
1 align: IconAlignmentType; ° d ONLN dÒa <lE *
5 theIconSuite: Handle): OSErr; ° d ONLN d 'u <Ä ˇ *'FUNCTION IconIDToRgn(theRgn: RgnHandle; ° d ONLN d O <ä *
$ iconRect: Rect; ° d ONLN d tâ <î" *
. align: IconAlignmentType; ° d ONLN d £ì <û *
- iconID: INTEGER): OSErr; ◊ X◊
*2 Drawing Icons the System 7 Way (Ïˇ7 ) of 12 ˇ§ ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘ ,
Courier
° d ONLN d ( Ô *+FUNCTION IconMethodToRgn(theRgn: RgnHandle; ° d ONLN d , ' 2 ‡ *
( iconRect: Rect; ° d ONLN d U 1 < *
2 align: IconAlignmentType; ° d ONLN d à ; F *
/ theMethod: IconGetter; ° d ONLN d ∏ E P *
2 yourDataPtr: Ptr): OSErr;
° d ONLN d Î \ h ` *These routines ° d ONLN d ˙ \ ` hç )H?will create a region from the mask of the icon selected by the ° d ONLN d9 [ç g≈ ( Ñ´iconRect ° d ONLN dA \≈ h⁄ )8 and ° d ONLN dF h t ; ( ë 6align ° d ONLN dK i ; u¡ )#T values passed. They will allow you to do accurate hit testing and outline dragging ° d ONLN dü i¡ u⁄ ( ëflof an ° d ONLN d• v Ç W ( û 6
icon in your ° d ONLN d≤ v W Ç ™ )?application. The ° d ONLN d√ u ™ Å È )S RgnHandle ° d ONLN dà v È Ç⁄ )?/ must have been previously allocated before you ° d ONLN d¸ Ç é \ ( ™ 6make this call.
° d ONLN d ö • ‡ *(FUNCTION RectInIconSuite(testRect: Rect; ° d ONLN d5 § Ø ‡ *
( iconRect: Rect; ° d ONLN d^ Æ π *
2 align: IconAlignmentType; ° d ONLN dë ∏ √0 *
8 theIconSuite: Handle): BOOLEAN; ° d ONLN d à ◊ — *%FUNCTION RectInIconID(testRect: Rect; ° d ONLN d ÷ · — *
% iconRect: Rect; ° d ONLN d ‡ Î *
/ align: IconAlignmentType; ° d ONLN dF Í ı *
0 iconID: INTEGER): BOOLEAN; ° d ONLN dw ˛ Â *)FUNCTION RectInIconMethod(testRect: Rect; ° d ONLN d° Â *
) iconRect: Rect; ° d ONLN dÀ *
3 align: IconAlignmentType; ° d ONLN dˇ ' *
0 theMethod: IconGetter; ° d ONLN d0& 1! *
5 yourDataPtr: Ptr): BOOLEAN; ° d ONLN df: E — *%FUNCTION PtInIconSuite(testPt: Point; ° d ONLN dåD O ÷ *
& iconRect: Rect; ° d ONLN d≥N Y *
0 align: IconAlignmentType; ° d ONLN d‰X c& *
6 theIconSuite: Handle): BOOLEAN; ° d ONLN dl w ¬ *"FUNCTION PtInIconID(testPt: Point; ° d ONLN d>v Å « *
° d ONLN d£‹ Ë *.These calls hit test the passed Point or Rect ° d ONLN d—‹Ë⁄ )È*against the icon indicated. The parameters ° d ONLN d¸Ë Ù P ( 6iconRect ° d ONLN dÈ Pı g )8 and ° d ONLN d Ë gÙ ä )align ° d ONLN dÈ äı∏ )#@, and the grafPort should be the same as when the icon was last ° d ONLN dNÈ∏ı⁄ (÷drawn. ° d ONLN dUı \ ( 6The functions ° d ONLN dcı \⁄ )DTreturn true if the point is in the icon mask or if the rectangle intersects the icon ° d ONLN d∏
5 () 6mask.
° d ONLN dæ% 4 k *' Error Codes
° d ONLN d @ Lõ *RThe Icon Utilities will pass back any errors encountered during execution, so you ° d ONLN d @õL⁄ (hπ
can expect to ° d ONLN d*L XW (t 6>see Memory Manager, Resource Manager, and other normal errors. ° d ONLN did p Æ * There is one error code defined ° d ONLN dâd Æp⁄ )ñAspecifically for the Icon Utilities routines that may be returned ° d ONLN dÀp | ° (ò 6 by the Icon plotting routines. ◊ 4◊˘
*T8 ) of 12 (Ïq Drawing Icons the System 7 Way ˇé ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +Z-Developer Support Center ( -Ê October 1992 / X / ,
Courier
° d ONLN d ) < 4 n ( P Z
{ Pascal } ° d ONLN d 3 < > U *
CONST ° d ONLN d = ` H ƒ +$
noMaskFound = -1000; ° d ONLN d ' G < R P ( n ZEND; ° d ONLN d , [ < f _ */* C */ ° d ONLN d 4 e < p õ *
#define noMaskFound ° d ONLN d H e ® p ¡ )l-1000
° d ONLN d N { < á ≈ ( £ Z This error will be returned if ° d ONLN d m { ≈ Რ)âBthe Icon Utilities package could not find or create a mask for the ° d ONLN d ∞ á < ìH ( Ø Z;icon family. The Icon Utilities will use the correct mask ° d ONLN d Î áH ì˛ ( Øf(for each icon size, if one is available. ° d ONLN d ì < ü& ( ª Z4If no mask for a specific size is available, a mask ° d ONLN dI ì& ü˛ )Í,will be created from any mask in the family, ° d ONLN dv ü < ´¸ ( « Zebut if there are no 1 bit images and no mask in the family, plotting calls will fail with this error.
° d ONLN d‹ √ < “7 *'$Type(def)s and Glue for Pascal and C
° d ONLN d fi < Í fi * The Pascal and C interfaces are ° d ONLN d! fi fi Ͳ )¢5provided here to copy and paste since the current MPW ° d ONLN dW Í < ˆ í ( Zstandard interface ° d ONLN dj Í í ˆ˛ )VOfiles do not contain the glue for these calls. Electronic versions of this note ° d ONLN d∫ ˆ < R ( Zare ° d ONLN dæ ˆ R˛ )Mon AppleLink (Developer Support: Developer Services: Technical Documentation: ° d ONLN d </ (* Z.Macintosh Technical Notes: Imaging: Graphics: ° d ONLN d:/˛ )Û(Icon Drawing in 7.sit (Stuffit)) and the ° d ONLN dc <â (6 ZBDeveloper CD (Technical Documentation: Macintosh Technical Notes: ° d ONLN d•â˛ (6ßImaging: Graphics: Icon ° d ONLN dΩ <& Ç (B ZDrawing in 7). ° d ONLN dÃ2 <>Œ *QMPW C, Pascal, and Assembler files also have been submitted to AppleLink and the ° d ONLN d 2Œ>˛ (ZÏ Developer ° d ONLN d'> <Jl (f Z>CD, but their paths were not known when this note was written.
2 ⁄= fl )e ° d ONLN d 2 fl= ‰ )I ° d ONLN d 2 ‰= È )c ° d ONLN d
2 È= Ó )o ° d ONLN d2 Ó= Û )n ° d ONLN d2 Û= ¯ )D ° d ONLN d2 ¯= ˝ )a ° d ONLN d2 ˝= )t ° d ONLN d2= )a ° d ONLN d2= ): ° d ONLN d2 = ) ° d ONLN d2= )H ° d ONLN d2= )a ° d ONLN d2= )n ° d ONLN d2 =% )d ° d ONLN d2%=* )l ° d ONLN d2*=/ )e ° d ONLN d2/=4 ); ° d ONLN d 24=9 ) ° d ONLN d 29=> )t ° d ONLN d 2>=C )h ° d ONLN d 2C=H )e ° d ONLN d 2H=M )S ° d ONLN d!2M=R )u ° d ONLN d"2R=W )i ° d ONLN d#2W=\ )t ° d ONLN d$2\=a )e ° d ONLN d%2a=f ): ° d ONLN d&2f=k ) ° d ONLN d'2k=p )H ° d ONLN d(2p=u )a ° d ONLN d)2u=z )n ° d ONLN d*2z= )d ° d ONLN d+2=Ñ )l ° d ONLN d,2Ñ=â )e ° d ONLN d-2â=é ); ° d ONLN d.2é=ì ) ° d ONLN d/2ì=ò )t ° d ONLN d02ò=ù )h ° d ONLN d12ù=¢ )e ° d ONLN d22¢=ß )T ° d ONLN d32ß=¨ )y ° d ONLN d42¨=± )p ° d ONLN d52±=∂ )e ° d ONLN d62∂=ª ): ° d ONLN d8< <G A (c ZR ° d ONLN d9< AG F )e ° d ONLN d:< FG K )s ° d ONLN d;< KG P )T ° d ONLN d<< PG U )y ° d ONLN d=< UG Z )p ° d ONLN d>< ZG _ )e ° d ONLN d?< _G d )) ° d ONLN d@< dG i ): ° d ONLN dA< iG n ) ° d ONLN dB< nG s )O ° d ONLN dC< sG x )S ° d ONLN dD< xG } )E ° d ONLN dE< }G Ç )r ° d ONLN dF< ÇG á )r ° d ONLN dG< áG å ); ° d ONLN dIF <Q ı (m Z% INLINE $303C, $0609, $ABC9; ° d ONLN doP <[Ω *
MFUNCTION ForEachIconDo(theSuite: Handle; selector: IconSelectorValue; action: ° d ONLN dΩZ <e s *
IconAction; ° d ONLN d…d <o, *
0 yourDataPtr: Ptr): OSErr; ° d ONLN d˙n <y ı *
% INLINE $303C, $060A, $ABC9; ° d ONLN d x <ÉÜ *
BFUNCTION GetIconSuite(VAR theIconSuite: Handle; theResID: INTEGER; ° d ONLN d cÇ <ç^ *
: selector: IconSelectorValue): OSErr; ° d ONLN d ûå <ó ı *
% INLINE $303C, $0501, $ABC9; ° d ONLN d ƒñ <°Ω *
MFUNCTION DisposeIconSuite(theIconSuite: Handle; disposeData: BOOLEAN): OSErr; ° d ONLN d
† <´ ı *
% INLINE $303C, $0302, $ABC9; ◊ X◊
*% Drawing Icons the System 7 Way (Ïˇ9 ) of 12 ˇh ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘ ,
Courier
° d ONLN d (ä *JFUNCTION PlotIconSuite(theRect: Rect; align: IconAlignmentType; transform: ° d ONLN d K ' 2 r *
IconTransformType; ° d ONLN d ^ 1 < *
4 theIconSuite: Handle): OSErr; ° d ONLN d ì ; F Ã *
$ INLINE $303C, $0603, $ABC9; ° d ONLN d ∏ E Pg *
CFUNCTION MakeIconCache(VAR theHandle: Handle; makeIcon: IconGetter; ° d ONLN d ¸ O Z! *
5 yourDataPtr: UNIV Ptr): OSErr; ° d ONLN d2 Y d — *
% INLINE $303C, $0604, $ABC9; ° d ONLN dX c nä *
JFUNCTION LoadIconCache(theRect: Rect; align: IconAlignmentType; transform: ° d ONLN d£ m x r *
IconTransformType; ° d ONLN d∂ w Ç *
4 theIconCache: Handle): OSErr; ° d ONLN dÎ Å å — *
% INLINE $303C, $0606, $ABC9; ° d ONLN d ã ñX *
@FUNCTION PlotIconMethod(theRect: Rect; align: IconAlignmentType; ° d ONLN dR ï †î *
L transform: IconTransformType; theMethod: IconGetter; ° d ONLN dü ü ™& *
of 12 (Ïq Drawing Icons the System 7 Way ˇ4 ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +Z-Developer Support Center ( -Ê October 1992 / X / ,
Courier
° d ONLN d < (¬ ( D ZN transform: IconTransformType; theCIcon: CIconHandle): ° d ONLN d O ' < 2 Z *
OSErr; ° d ONLN d V 1 < < ı *
% INLINE $303C, $061F, $ABC9; ° d ONLN d | O < Z å * /* C Typedefs */ ° d ONLN d ç c < n≥ *Ktypedef pascal OSErr (*IconAction)(ResType theType, Handle *theIcon, void ° d ONLN d Ÿ m < x Ç *
Ipascal OSErr PlotIconHandle(const Rect *theRect, IconAlignmentType align, ° d ONLN d%g rÄ *
H IconTransformType transform, Handle theIcon) ° d ONLN dnq | « *
# = {0x303C, 0x061D, 0xABC9}; ° d ONLN dí{ ÜÖ *
Ipascal OSErr PlotSICNHandle(const Rect *theRect, IconAlignmentType align, ° d ONLN d‹Ö êÄ *
H IconTransformType transform, Handle theSICN) ° d ONLN d%è ö « *
# = {0x303C, 0x061E, 0xABC9}; ° d ONLN dIô §ä *
Jpascal OSErr PlotCIconHandle(const Rect *theRect, IconAlignmentType align, ° d ONLN dî£ Æ£ *
O IconTransformType transform, CIconHandle theCIcon) ° d ONLN d‰≠ ∏ « *
# = {0x303C, 0x061F, 0xABC9};
° d ONLN d€ Á Ç */Further Reference: 4˘ ° d ONLN dË *Ù . +
• ° d ONLN d Ë <Ù ç )Inside Macintosh ° d ONLN d-Ë çÙ& )Q , Volume V, QuickDraw chapter ° d ONLN dKÙ * . ( H• ° d ONLN dMÙ < ç )Inside Macintosh ° d ONLN d]Ù ç ? )Q%, Volume VI, Finder Interface chapter ◊ 4◊˘
(Ï 612 )
of 12 (Ïq Drawing Icons the System 7 Way ˇn ◊# ˇ ˇˇˇˇ # ◊ † Ç
/ Z Å#
0Ià:µú9 " { ˇˇˇˇˇˇˇˇ # † ƒ ° d
ONLN f ˛ † å ° d 1drw2 … -·_ Ä ˇˇˇˇˇˇ è ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˙ ó@ † ò , Times
. R… R… +]BNew Technical Notes † ô ° d drw2 : °„ † ó ° d 1drw2 eÙ Ä ˇˇˇˇˇˇ P ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä E¿ † ò
( {ïDeveloper Support † ô ° d drw2 : °„ † ó ° d `drw2 - Ô ˇˇˇˇˇˇ K Ô - Z f f Z ° d 1drw2 ¿˙È ˇˇˇˇˇˇ K ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : 0 ° ö ˇÙ Ä † ò
0 ( UÔ † ô ° d drw2 : °„ † ó ° d 1drw2 ÔÊ˙ ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˝Ä † ò
+& ® † ô ° d drw2 : °„ † ó ° d 1drw2  -¯ y ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä % † ò
( Z \ Macintosh † ô ° d drw2 : °„ † ó † ç ° d drw2 D † É
IR . ° d ONLN dˇˇ ( ß ZDisplaying Large PICT Files
° d ONLN dˇˇ *Imaging ° d ONLN dˇˇ ( ∑±M.IM.LargePict
° d ONLN dˇˇ ( œ Z Revised by: ° d ONLN dˇˇ ( œ„
March 1988 ° d ONLN dˇˇ ( € Z Written by: ° d ONLN dˇˇ )H Rick Blair ° d ONLN dˇˇ ( €Ì July 1987 ° d ONLN dˇˇ ( Û Z>Now that we have scanners and other massive-picture producing ° d ONLN dˇˇ ( Ûé types of applications, there is ° d ONLN dˇˇ ( ˇ Z(a need to address the problem of how to ° d ONLN dˇˇ )…2display a PICT format object that is bigger than a ° d ONLN dˇˇ ( ZAcurrent PICT resource is allowed to be. Note that this technique ° d ONLN dˇˇ ( â applies equally well to version ° d ONLN dˇˇ ( ZG1 and version 2 (word-opcode) pictures as produced by the Macintosh II. & X&
° d ONLN dˇˇ *4Future Compatibility
° d ONLN dˇˇ *"Think of the handle returned by a ,
Courier ° d ONLN dˇˇ )ßGetResource('PICT',ID) ° d ONLN dˇˇ )ö as a “handle” ° d ONLN dˇˇ )H in the more ° d ONLN dˇˇ (p ZMgeneral sense of being an abstract “tag”—something that the ROM routines can ° d ONLN dˇˇ (p—use to draw the ° d ONLN dˇˇ (| ZPpicture with. Don’t assume that the entire picture has been read into memory or ° d ONLN dˇˇ (|fl that you can ° d ONLN dˇˇ (â Z)directly read any bytes beyond the basic ° d ONLN dˇˇ )ΔPicture ° d ONLN dˇˇ )1 record structure ( ° d ONLN dˇˇ )ZpicSize ° d ONLN dˇˇ )1 followed by ° d ONLN dˇˇ (ñ ZpicFrame ° d ONLN dˇˇ )8:). Someday we may provide a mechanism for the resource to ° d ONLN dˇˇ (ñøbe disk- instead of ° d ONLN dˇˇ (¢ ZLmemory-based. The QuickDraw bottleneck procedures will know how to get data ° d ONLN dˇˇ (¢› from and put ° d ONLN dˇˇ (Æ Z#data into the pictures in any case.
° d ONLN dˇˇ *'Spooling from a PICT file
° d ONLN dˇˇ **In order to display pictures of arbitrary ° d ONLN dˇˇ )»1size, your application should be able to import a ° d ONLN dˇˇ (˘ ZQuickDraw picture from a ° d ONLN dˇˇ )~Afile of type PICT. This is the file produced by a “Save as…” from ° d ONLN dˇˇ ( Z&MacDraw with the PICT option selected. ° d ONLN dˇˇ *?What follows is a small program fragment that demonstrates how ° d ONLN dˇˇ ( õto spool in a picture from ° d ONLN dˇˇ () Z[the data fork ° d ONLN dˇˇ )BQof] a PICT file. The picture can be larger than the historical 32K resource size. ° d ONLN dˇˇ (6 Z6See technical note #88 if you are unfamiliar with the ° d ONLN dˇˇ (6\Signal ° d ONLN dˇˇ )* mechanism. We assume that ° d ONLN dˇˇ )ëa ° d ONLN dˇˇ (C Z CatchSignals ° d ONLN dˇˇ )T has been done before ° d ONLN dˇˇ )jGetandDrawPICTFile
° d ONLN dˇˇ )~
° d ONLN dˇˇ )
is called.
° d ONLN dˇˇ (j ZMPW Pascal Example
° d ONLN dˇˇ +$1{the following variable must be at the top level} ° d ONLN dˇˇ *VAR ° d ONLN dˇˇ *
@ globalRef : INTEGER; {refNum of the file to read from} ° d ONLN dˇˇ *2{the following procedure must be at the top level} ° d ONLN dˇˇ *8PROCEDURE GetPICTData(dataPtr: Ptr; byteCount: INTEGER); ◊ X◊
(Ï ZDisplaying Large PICT Files (Ï1 ) of 5 ˇ ° ¿Ù%%DSIDICT:_cv
currentdict /bu known {bu}if
userdict /_cv known not{userdict /_cv 30 dict put}if
_cv begin
/bdf{bind def}bind def
currentscreen/cs exch def/ca exch def/cf exch def
/setcmykcolor where{/setcmykcolor get /cvcmyk exch def}{/cvcmyk{1 sub 4 1 roll 3{3 index add neg dup 0 lt{pop 0}if 3 1 roll}repeat setrgbcolor pop}bdf }ifelse
/ss{//cf //ca //cs setscreen}bdf
/stg{ss setgray}bdf
/strgb{ss setrgbcolor}bdf
/stcmyk{ss cvcmyk}bdf
/min1{dup 0 eq{pop 1}if}bdf
end
currentdict /bn known {bn}if
† ø ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘ ,
Courier
° d ONLN d < (6 +$2{replacement for the QuickDraw bottleneck routine} ° d ONLN d 4 1 < < Z * VAR ° d ONLN d < ; < F æ *
err : OSErr; ° d ONLN d X E < P » *
longCount : LONGINT; ° d ONLN d v Y < d d * BEGIN ° d ONLN d Ä c < n Õ *
longCount := byteCount; ° d ONLN d ü m < x1 *
1 err := FSRead(globalRef,longCount,dataPtr); ° d ONLN d “ w < Çü *
G {can't check for an error because we don't know how to handle it} ° d ONLN d Å < å _ *
END; ° d ONLN d$ ï < † U *CONST ° d ONLN d+ ü < ™Ü *
@ SFGetFile(wher,'',NIL,numFileTypes,myFileTypes,NIL,reply); ° d ONLN d[ô <§ “ * IF reply.good THEN BEGIN ° d ONLN d{£ <ÆÅ *
A SetStdProcs(myProcs); {use SetStdCProcs for a CGrafPort} ° d ONLN dæ≠ <∏ *
, myProcs.getPicProc := @GetPICTData; ° d ONLN dÏ∑ <¬ö *
F savedProcs := thePort^.grafProcs; {set the grafProcs to ours} ° d ONLN d4¡ <Ã *
( thePort^.grafProcs := @myProcs; ° d ONLN d^’ <‡r *> myPicture := PicHandle(NewHandle(SizeOf(myPicture))); ° d ONLN dûÈ <Ùm *= Signal(FSOpen(reply.fname,reply.vRefNum,globalRef)); ° d ONLN d›Û <˛ã *
C Signal(GetEOF(globalRef,myEOF)); {get EOF for later check} ° d ONLN d"˝ <Ü *
B Signal(SetFPos(globalRef,fsFromStart,512)); {skip header} ° d ONLN df < h *< {read in the (obsolete) size word and the picFrame} ° d ONLN d§ <& *
( longCount := SizeOf(myPicture); ° d ONLN dŒ% <0m *
= Signal(FSRead(globalRef,longCount,Ptr(myPicture^))); ° d ONLN d
9 <D§ *H DrawPicture(myPicture,myPicture^^.picFrame); {draw the picture} ° d ONLN dWM <Xï *E Signal(GetFPos(globalRef,filePos)); {get position for check} ° d ONLN dûW <b *
$ Signal(FSClose(globalRef)); ° d ONLN dƒk <v *) DisposHandle(Handle(myPicture)); ° d ONLN dÔ <är *> thePort^.grafProcs := savedProcs; {restore the procs} ° d ONLN d/ì <ûY *9 {Check for errors. If there wasn't enough room,} ° d ONLN djù <®Y *
9 {DrawPicture will abort; the FILE position mark} ◊ 4◊˘
C/*can't check for an error because we don't know how to handle it*/ ° d ONLN dÈ ˙ < õ (! Z} /* GetPICTData */ ° d ONLN d˝ < ı *%/*error code if DrawPicture aborted*/ ° d ONLN d# <# _ *
#define ° d ONLN d+ Ñ# Ë )H abortPICT 128 ° d ONLN dI, <7 Ø (S ZOSErr GetDrawPICTFile() ° d ONLN db, 7Ã )¥,/*read in a PICT FILE selected by the user*/ ° d ONLN dè@ <K A (g Z{ ° d ONLN dë@ `K … )$/* GetDrawPICTFile */ ° d ONLN d´T `_ ~ *Point ° d ONLN d≥T ®_ Δ )Hwher; ° d ONLN dªT _w )H/*where to display dialog*/ ° d ONLN dÿ^ `i É (Ö ~SFReply ° d ONLN d‡^ ®i – )Hreply; ° d ONLN dÈ^ i@ )H/*reply record*/ ° d ONLN d˚h `s í (è ~
SFTypeList ° d ONLN dh ®s ‰ )H myFileTypes; ° d ONLN dh sÜ )H /*more Standard FILE goodies*/ ° d ONLN d3r `} ~ (ô ~short ° d ONLN d;r ®} È )H
numFileTypes; ° d ONLN dJ| `á y (£ ~OSErr ° d ONLN dQ| ®á º )Herr; ° d ONLN dWÜ `ë í (≠ ~
QDProcsPtr ° d ONLN dbÜ ®ë fl )H savedProcs; ° d ONLN doê `õ É (∑ ~QDProcs ° d ONLN dwê ®õ – )HmyProcs; ° d ONLN dÄê õü )H#/*use CQDProcs for a color window*/ ° d ONLN d•ö `• ç (¡ ~ PicHandle ° d ONLN dØö ®• ⁄ )H
myPicture; ° d ONLN d∫ö •Ã )H,/*we need a picture handle for DrawPicture*/ ° d ONLN d˧ `Ø t (À ~long ° d ONLN dÓ§ ®Ø )HlongCount,myEOF,filePos; ° d ONLN d∏ `√ ∫ (fl ~ wher.h = 20; ° d ONLN d ¬ `Õ ∫ *
wher.v = 20; ° d ONLN d0Ã `◊ ˆ *
numFileTypes = 1; ° d ONLN dQÃ\◊ )¸/*display PICT files*/ ° d ONLN di÷ `· ˆ (˝ ~ myFileTypes[0] = 'PICT'; ° d ONLN d⇠`Ε *
A SFGetFile(wher,'',nil,numFileTypes,myFileTypes,nil,&reply); ◊ X◊
(Ï ZLarge PICT Files (Ï3 ) of 5 ˇt ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘ ,
Courier
° d ONLN d ' < 2 • +$! if (reply.good) ° d ONLN d 1 ` < e +$
{ ° d ONLN d ; Ñ F Ú +$
SetStdProcs(&myProcs); ° d ONLN d 9 E Ñ P8 *
$/*use SetStdCProcs for a CGrafPort*/ ° d ONLN d _ O < Z i ( v Z ° d ONLN d i O Ñ Z) )H!myProcs.getPicProc = GetPICTData; ° d ONLN d å Y < d i ( Ä Z ° d ONLN d ñ Y Ñ d= )H%savedProcs = (*qd.thePort).grafProcs; ° d ONLN d ø m Ñ x * /*set the grafProcs to ours*/ ° d ONLN d fi w < Ç i ( û Z ° d ONLN d Ë w Ñ Ç3 )H#(*qd.thePort).grafProcs = &myProcs; ° d ONLN d
if (err != noErr) return err; ° d ONLN d§ Ω < » U ( ‰ Z ° d ONLN d™ Ω ` » e )$ ° d ONLN d¨ Ω Ñ » )$ err = GetEOF(globalRef,&myEOF); ° d ONLN dœ « Ñ “ *
/*get EOF for later check*/ ° d ONLN dÓ — Ñ ‹ *
if (err != noErr) return err; ° d ONLN d Â Ñ ú *8err = SetFPos(globalRef,fsFromStart,512);/*skip header*/ ° d ONLN dI Ô < ˙ i ( Z ° d ONLN dS Ô Ñ ˙ )H if (err != noErr) return err; ° d ONLN dr < i (* Z ° d ONLN d| Ñç )H5/*read in the (obsolete) size word and the picFrame*/ ° d ONLN d≥
< i (4 Z ° d ONLN dΩ
Ñ )H longCount = sizeof(Picture); ° d ONLN d€ <" d (> Z ° d ONLN d‰ Ñ"à )H4 err = FSRead(globalRef,&longCount,(Ptr)*myPicture); ° d ONLN d! <, i (H Z ° d ONLN d$! Ñ, )H if (err != noErr) return err; ° d ONLN dC5 <@ i (\ Z ° d ONLN dM5 Ñ@ó )H7DrawPicture(myPicture,&(**myPicture).picFrame); /*draw ° d ONLN då?JU +ê
the picture*/ ° d ONLN dùS Ñ^ç (z ¢5err = GetFPos(globalRef,&filePos);/*get position for ° d ONLN d⁄]h7 +ê
check*/ ° d ONLN d„g <r i (é Z ° d ONLN dÌg Ñr )H if (err != noErr) return err; ° d ONLN d q <| i (ò Z ° d ONLN dq Ñ| )Herr = FSClose(globalRef); ° d ONLN d1{ <Ü i (¢ Z ° d ONLN d;{ ÑÜ )H if (err != noErr) return err; ° d ONLN dZè <ö i (∂ Z ° d ONLN ddè Ñö$ )H DisposHandle((Handle)myPicture); ° d ONLN dÜ£ <Æ i ( Z ° d ONLN dê£ ÑÆÉ )H3(*qd.thePort).grafProcs = savedProcs;/*restore the ° d ONLN dÀ≠∏7 +ê
procs*/ ° d ONLN d‘¡ <à d (Ë Z ° d ONLN d›¡ ÑÃÉ )H3 /*Check for errors. if there wasn't enough room,*/ ° d ONLN dÀ <÷ d (Ú Z ° d ONLN dÀ Ñ÷É )H3 /*DrawPicture will abort; the FILE position mark*/ ° d ONLN dP’ <‡ i (¸ Z ° d ONLN dZ’ ч8 )H$/*won't be at the end of the FILE.*/ ° d ONLN dÇÈ ÑÙL *(if (filePos != myEOF) return abortPICT; ° d ONLN dÆÛ Ñ˛ fi *
else return noErr; ° d ONLN d¬˝ < » ($ Z } /*if (reply.good) */ ° d ONLN dfl " (. 6} ° d ONLN d‚ < • )$/* GetDrawPICTFile */
° d ONLN d¯) 8 Â (T 6 More on Picture Compatibility
° d ONLN dD P ô *Many applications already ° d ONLN d0D ôP⁄ )Å:support PICT resources larger than 32K. The 128K ROMs (and ° d ONLN dkP \ ‰ (x 6)later) allow pictures as large as memory ° d ONLN dîP ‰\⁄ )Ã-(or spooling) will accommodate. This was made ° d ONLN d¬\ h Œ (Ñ 6$possible by having QuickDraw ignore ° d ONLN dÊ\ Œh÷ )∂7the size word and simply read the picture until the end ° d ONLN d \÷h⁄ (ÑÙ- ° d ONLN d h t ¨ (ê 6 of-picture opcode was reached. ° d ONLN d=Ä å√ *WFor maximum safety and convenience, let QuickDraw generate and interpret your pictures. ◊ 4◊˘
() Z-sure that you have the latest specifications. ° d ONLN do <%· *UApple does not guarantee that a picture which wasn’t produced by QuickDraw will work. ° d ONLN d≈I <U ¶ *0Further Reference: t Xt ° d ONLN dÿV Nb R +
• ° d ONLN d⁄V `b ñ ) QuickDraw ° d ONLN d‰b Nn R (ä l• ° d ONLN dÊb `n# )$Technical Note M.IM.PictureOpcodes — ° d ONLN d
n Ñz Ò +$ Internal Picture Format ° d ONLN d%z NÜ R (¢ l• ° d ONLN d'z `Ü ¸ ) Technical Note M.PT.Signals — ° d ONLN dGÜ Ñí ß +$ Signals ◊ X◊
ONLN f ˛ † å ° d 1drw2 … -·_ Ä ˇˇˇˇˇˇ è ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˙ ó@ † ò , Times
. R… R… +]BNew Technical Notes † ô ° d drw2 : °„ † ó ° d 1drw2 eÙ Ä ˇˇˇˇˇˇ P ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä E¿ † ò
( {ïDeveloper Support † ô ° d drw2 : °„ † ó ° d `drw2 - Ô ˇˇˇˇˇˇ K Ô - Z f f Z ° d 1drw2 ¿˙È ˇˇˇˇˇˇ K ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : 0 ° ö ˇÙ Ä † ò
0 ( UÔ † ô ° d drw2 : °„ † ó ° d 1drw2 ÔÊ˙ ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˝Ä † ò
+& ® † ô ° d drw2 : °„ † ó ° d 1drw2  -¯ y ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä % † ò
( Z \ Macintosh † ô ° d drw2 : °„ † ó † ç ° d drw2 D † É
IR . ° d ONLN d n < Å ( õ ZLaserWriter Utility Q&As
° d ONLN d Ä < è r *Imaging ° d ONLN d ! Äu è˛ ( ´ìM.IM.LWUtil.Q&As
° d ONLN d 2 õ < ß t ( √ Z Revised by: ° d ONLN d > õ Ñ ß ˇ )HDeveloper Support Center ° d ONLN d W õæ ߲ ( √‹ October 1992 ° d ONLN d d ß < ≥ q ( œ Z Written by: ° d ONLN d p ß Ñ ≥ ˇ )HDeveloper Support Center ° d ONLN d â ßæ ≥˛ ( œ‹ October 1990 ° d ONLN d ñ ø < À ⁄ ( Á Z This Technical Note contains a ° d ONLN d µ ø ⁄ À˛ )û9collection of Q&As relating to a specific topic—questions ° d ONLN d Ô À < ◊† ( Û ZGyou’ve sent the Developer Support Center (DSC) along with answers from ° d ONLN d6 À† ◊˛ ( Ûæthe DSC engineers. ° d ONLN dI ◊ < „ u ( ˇ Z
While DSC ° d ONLN dS ◊ u „˛ )9Lengineers have checked the Q&A content for accuracy, the Q&A Technical Notes ° d ONLN d† „ < Ô q ( Z don’t have ° d ONLN d´ „ q Ô˛ )5Qthe editing and organization of other Technical Notes. The Q&A function is to get ° d ONLN d˝ Ô < ˚ Ÿ ( Z new technical information and ° d ONLN d Ô Ÿ ˚˛ )ù6updates to you quickly, saving the polish for when the ° d ONLN dR ˚ < (# Z,information migrates into reference manuals. ° d ONLN d < k *:Q&As are now included with Technical Notes to make access ° d ONLN dπk ˛ (;â to technical updates easier for ° d ONLN dŸ <+. (G Z/you. If you have comments or suggestions about ° d ONLN d .+˛ )Ú*Q&A content or distribution, please let us ° d ONLN d3+ <7 \ (S Zknow ° d ONLN d8+ \7˛ ) Iby sending an AppleLink to DEVFEEDBACK. Apple Partners may send technical ° d ONLN dÇ7 <Ci (_ Z9questions about Q&A content to DEVSUPPORT for resolution. ° d ONLN dºO <[« *NNew Q&As and Q&As revised this month are marked with a bar in the side margin. "n Ü XÜ
° d ONLN d Ä <è‹ *49SCSI drive format for LaserWriter II NTX with Rev. 3 ROMs
° d ONLN dEè <õ b * Written: ° d ONLN dNè àõ ¶ )L5/3/91 ° d ONLN dUõ <ß Å (√ ZLast reviewed: ° d ONLN ddõ àß ¨ )L6/26/91 ° d ONLN dl≥ <øW (€ Z<What could be causing intermittent PostScript errors from a ° d ONLN d®≥Wø˛ (€u LaserWriter II NTX with an SCSI ° d ONLN d»ø <ÀU (Á Z9hard disk mounted after installing the Rev 3 ROM upgrade? ° d ONLN dÀ <◊ N * ___ ° d ONLN d„ <Ô~ *>The LaserWriter II NTX with Rev 3 ROMs does not work properly ° d ONLN dD„~Ô˛ ( úwith a hard disk formatted ° d ONLN d_Ô <˚ e ( Z with the ° d ONLN dhÔ e˚˛ ))SLaserWriter Font Utility 1.x. You need to reformat the disk and copy the fonts back ° d ONLN dº˚ < ¬ (# Z onto the hard disk using the ° d ONLN dŸ˚ ¬˛ )ÜALaserWriter Font Utility 2.0.2. Unfortunately, there is no way to ° d ONLN d < Ω (/ Zmake this procedure easier.
° d ONLN d7+ <:π *':LaserWriter Font Utility copies Postscript file to printer
° d ONLN dr: <F b * Written: ° d ONLN d{: àF ¨ )L9/23/91 ° d ONLN dÉF <R Å (n ZLast reviewed: ° d ONLN díF àR ¨ )L10/8/91 ° d ONLN dö^ <j£ (Ü ZQIs there a utility that will send a PostScript file from disk to the LaserWriter? ° d ONLN dÏj <v N * ___ ° d ONLN dÇ <é é *The LaserWriter ° d ONLN d Ç éé˛ )RJFont Utility handles this job and is part of the System 7 disk set. On the ° d ONLN dKé <ö À (∂ ZSystem 7 Golden Master CD, ° d ONLN dfé Àö˛ )è?the path is System 7.0: System Software 7.0: Installer Version: ° d ONLN d¶ö <¶ Ä (¬ ZTidbits folder. ◊ X◊
** LaserWriter Font Utility Q&As (Ï1 ) of 1 ˇ ° ¿Ù%%DSIDICT:_cv
currentdict /bu known {bu}if
userdict /_cv known not{userdict /_cv 30 dict put}if
_cv begin
/bdf{bind def}bind def
currentscreen/cs exch def/ca exch def/cf exch def
/setcmykcolor where{/setcmykcolor get /cvcmyk exch def}{/cvcmyk{1 sub 4 1 roll 3{3 index add neg dup 0 lt{pop 0}if 3 1 roll}repeat setrgbcolor pop}bdf }ifelse
/ss{//cf //ca //cs setscreen}bdf
/stg{ss setgray}bdf
/strgb{ss setrgbcolor}bdf
/stcmyk{ss cvcmyk}bdf
/min1{dup 0 eq{pop 1}if}bdf
end
currentdict /bn known {bn}if
† øT ◊# ˇ ˇˇˇˇ # ◊ ° d WORD S † å ° d WORD R… † Ç
/ Z Å#
0Ià:µú9 " { ˇˇˇˇˇˇˇˇ # † ƒ ° d
ONLN f ˛ † å ° d 1drw2 … -·_ Ä ˇˇˇˇˇˇ è ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˙ ó@ † ò , Times
. eRSeRS +]BNew Technical Notes † ô ° d drw2 : °„ † ó ° d 1drw2 eÙ Ä ˇˇˇˇˇˇ P ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä E¿ † ò
Ä ( {ïDeveloper Support † ô ° d drw2 : °„ † ó ° d `drw2 - Ô ˇˇˇˇˇˇ K Ô - Z f f Z ° d 1drw2 ¿˙È ˇˇˇˇˇˇ K ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : 0 ° ö ˇÙ Ä † ò
0 ( UÔ † ô ° d drw2 : °„ † ó ° d 1drw2 ÔÊ˙ ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˝Ä † ò
l +& ® † ô ° d drw2 : °„ † ó ° d 1drw2  -¯ y ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä % † ò
BÄ ( Z \ Macintosh † ô ° d drw2 : °„ † ó † ç ° d drw2 D † É ° d WORD † ç
IR . ° d ONLN d o < Çc ( ú Z!Drawing Into an Off-Screen Bitmap
° d ONLN d " Å < ê r *Imaging ° d ONLN d * Åc ê˛ ( ¨ÅM.IM.OffscreenBitMap
° d ONLN d ? ú < ® t ( ƒ Z Revised by: ° d ONLN d K ú Ñ ® )HJon Zap & Forrest Tanaka ° d ONLN d d úÕ ®˛ ( ƒÎ June 1990 ° d ONLN d n ® < ¥ q ( – Z Written by: ° d ONLN d z ® Ñ ¥) )H!Jim Friedlander & Ginger Jernigan ° d ONLN d ú ®œ ¥˛ ( –Ì July 1985 ° d ONLN d ¶ ¿ < à û ( Ë ZThis Technical Note ° d ONLN d ∫ ¿ û Ã˛ )bHprovides an example of creating an off-screen bitmap, drawing to it, and ° d ONLN d à < ÿ fi ( Ù Z#then copying from it to the screen. ° d ONLN d' ÿ < ‰ ÿ * Changes since April 1990: ° d ONLN d@ ÿ ÿ ‰# )ú Clarified the ° d ONLN dP ÿ# ‰˛ )K)section on window updates with off-screen ° d ONLN dz ‰ < e ( Z>bitmaps to explicitly limit these updates to your own windows. X ° d ONLN dπ < *%(The following is an example of creating ° d ONLN d· ˛ )≈1and drawing to an off-screen bitmap, then copying ° d ONLN d <!” (= ZQfrom it to an on-screen window. We supply this example in both MPW Pascal and C. ° d ONLN de- <9 É *
MPW Pascal ° d ONLN dpE <Q *'First, let’s look at a general purpose ° d ONLN dóE Q˛ )¥7function to create an off-screen bitmap. This function ° d ONLN dœR <^ t (z Z creates the ,
Courier ° d ONLN d€Q t] ¨ )8GrafPort ° d ONLN d„R ¨^ Ù )8 on the heap. ° d ONLN dÒR Ù^˛ )H3 You could also create it on the stack and pass the ° d ONLN d%^ <j: (Ü Z:uninitialized structure to a function similar to this one.
° d ONLN d`v <Å÷ *RFUNCTION CreateOffscreenBitMap(VAR newOffscreen:GrafPtr; inBounds:Rect) : BOOLEAN; ° d ONLN d≥ä <ï K *VAR ° d ONLN d∑î <ü ™ *
newPort : GrafPtr; ° d ONLN dÂ≤ <Ω U *BEGIN ° d ONLN dκ <«‡ *
T GetPort(savePort); {need this to restore thePort after OpenPort changes it} ° d ONLN d@– <€Æ *J newPort := GrafPtr(NewPtr(sizeof(GrafPort))); {allocate the GrafPort} ° d ONLN dã⁄ < · *
! IF MemError <> noErr THEN BEGIN ° d ONLN d≠‰ <ÔÆ *
J CreateOffscreenBitMap := false; {failed to allocate it} ° d ONLN d¯Ó <˘ ‹ *
EXIT(CreateOffscreenBitMap); ° d ONLN d¯ < Z *
END; ° d ONLN d <
K *
{ ° d ONLN d$ < *
, the OpenPort call does the following . . . ° d ONLN dR <!« *
O allocates space for visRgn (set to screenBits.bounds) and clipRgn (set wide ° d ONLN d¢ <+ U *
open) ° d ONLN d®* <5 ◊ *
sets portBits to screenBits ° d ONLN d»4 <? ˙ *
& sets portRect to screenBits.bounds ° d ONLN dÔ> <I √ *
etc. (see IM I-163,164) ° d ONLN d H <S *
* side effect: does a SetPort(offScreen) ° d ONLN d6R <] K *
} ° d ONLN d:\ <g † *
OpenPort(newPort); ° d ONLN dOf <qã *
C {make bitmap exactly the size of the bounds that caller supplied} ° d ONLN dìp <{ü *
G WITH newPort^ DO BEGIN {portRect, clipRgn, and visRgn are in newPort} ° d ONLN d€z <Ö π *
portRect := inBounds; ° d ONLN dıÑ <è∏ *
L RectRgn(clipRgn, inBounds); {avoid wide-open clipRgn, to be safe} ° d ONLN dBé <ô∏ *
L RectRgn(visRgn, inBounds); {in case inBounds is > screen bounds} ° d ONLN dèò <£ Z *
END; ◊ X◊
*-!Drawing Into an Off-Screen Bitmap (Ï1 ) of 6 ˇ ° ¿Ù%%DSIDICT:_cv
currentdict /bu known {bu}if
userdict /_cv known not{userdict /_cv 30 dict put}if
_cv begin
/bdf{bind def}bind def
currentscreen/cs exch def/ca exch def/cf exch def
/setcmykcolor where{/setcmykcolor get /cvcmyk exch def}{/cvcmyk{1 sub 4 1 roll 3{3 index add neg dup 0 lt{pop 0}if 3 1 roll}repeat setrgbcolor pop}bdf }ifelse
/ss{//cf //ca //cs setscreen}bdf
/stg{ss setgray}bdf
/strgb{ss setrgbcolor}bdf
/stcmyk{ss cvcmyk}bdf
/min1{dup 0 eq{pop 1}if}bdf
end
currentdict /bn known {bn}if
† ø÷ ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘ ,
Courier
° d ONLN d (ô *M WITH newPort^.portBits DO BEGIN {baseAddr, rowBytes and bounds are in ° d ONLN d N ' 2 @ *
newPort} ° d ONLN d W 1 < ã *
bounds := inBounds; ° d ONLN d o ; Fî *
L {rowBytes is size of row It must be rounded up to even number of bytes} ° d ONLN d º E Pg *
C rowBytes := ((inBounds.right - inBounds.left + 15) DIV 16) * 2; ° d ONLN d Y dD *< {number of bytes in BitMap is rowBytes * number of rows} ° d ONLN d= c n≤ *
R {see note at end of Technical Note about using _NewHandle rather than _NewPtr} ° d ONLN dê m xè *
K baseAddr := NewPtr(rowBytes * LONGINT(inBounds.bottom - inBounds.top)); ° d ONLN d‹ w Ç 6 *
END; ° d ONLN d„ Å åô *
M IF MemError <> noErr THEN BEGIN {see if we had enough room for the bits} ° d ONLN d1 ã ñ Ü *
SetPort(savePort); ° d ONLN dH ï †l *
D ClosePort(newPort); { dump the visRgn and clipRgn } ° d ONLN dç ü ™5 *
° d ONLN d %∏ *ZHere is the procedure to get rid of an off-screen bitmap created by the previous function:
° d ONLN dK1 <5 *9PROCEDURE DestroyOffscreenBitMap(oldOffscreen : GrafPtr); ° d ONLN dÖ; F 1 *
BEGIN ° d ONLN dãE P® *
P ClosePort(oldOffscreen); { dump the visRgn and clipRgn } ° d ONLN d‹O Zb *
B DisposPtr(oldOffscreen^.portBits.baseAddr); { dump the bits } ° d ONLN d Y db *
B DisposPtr(Ptr(oldOffscreen)); { dump the port } ° d ONLN dbc n , *
END;
° d ONLN dgy Öè *HNow that you know how to create and destroy an off-screen bitmap, let’s ° d ONLN dØyèÖ⁄ (°≠go through the ° d ONLN dæÜ í^ (Æ 6Dmotions of using one. First, let’s define a few things to make the ° d ONLN dÖ^ë§ (Æ|
_NewWindow ° d ONLN d Ü§íº )F call ° d ONLN dܺí⁄ )a little ° d ONLN dí û ; (∫ 6clearer.
° d ONLN d$™ µ 1 *CONST ° d ONLN d*¥ ø Ü *
kIsVisible = true; ° d ONLN dAæ … ã *
kNoGoAway = false; ° d ONLN dY» ” ê *
kMakeFrontWindow = -1; ° d ONLN dr“ › *
0 myString = 'The EYE'; {string to display}
° d ONLN d£Ë Ù ± *!Here’s the body of the test code:
3 CopyBits(offscreen^.portBits, myWindow^.portBits, ° d ONLN dÚ5 <@Ü *
B offscreen^.portRect, myWindow^.portRect, srcCopy, NIL); ° d ONLN d5I <Tm *= DestroyOffscreenBitMap(offscreen); {remove the evidence} ° d ONLN ds] <h« *O WHILE NOT Button DO; {give user a chance to see the results} ° d ONLN d√g <r P *
END.
° d ONLN d»} <â h *MPW C ° d ONLN dŒï <° *'First, let’s look at a general purpose ° d ONLN dıï °˛ )¥7function to create an off-screen bitmap. This function ° d ONLN d-¢ <Æ t ( Z creates the ° d ONLN d9° t≠ ¨ )8GrafPort ° d ONLN dA¢ ¨Æ Ù )8 on the heap. ° d ONLN dO¢ ÙÆ˛ )H3 You could also create it on the stack and pass the ° d ONLN dÉÆ <∫: (÷ Z:uninitialized structure to a function similar to this one.
° d ONLN dæΔ <—ê *DBoolean CreateOffscreenBitMap(GrafPtr *newOffscreen, Rect *inBounds) ° d ONLN d– <€ A *
{ ° d ONLN d⁄ <Â õ *
GrafPtr savePort; ° d ONLN d‰ <Ô ñ *
GrafPtr newPort; ° d ONLN d,¯ <Æ *J GetPort(&savePort); /* need this to restore thePort after OpenPort */ ° d ONLN dw <¬ *N newPort = (GrafPtr) NewPtr(sizeof(GrafPort)); /* allocate the grafPort */ ° d ONLN dΔ <! æ *
if (MemError() != noErr) ° d ONLN d· <+¬ *
N return false; /* failed to allocate the off-screen port */ ° d ONLN d0* <5 P *
/* ° d ONLN d54 <?' *
/ the call to OpenPort does the following . . . ° d ONLN df> <I« *
O allocates space for visRgn (set to screenBits.bounds) and clipRgn (set wide ° d ONLN d∂H <S U *
open) ° d ONLN dºR <] ◊ *
sets portBits to screenBits ° d ONLN d‹\ <g ˙ *
& sets portRect to screenBits.bounds ° d ONLN df <q √ *
etc. (see IM I-163,164) ° d ONLN d p <{ *
+ side effect: does a SetPort(&offScreen) ° d ONLN dKz <Ö P *
*/ ° d ONLN dPÑ <è † *
OpenPort(newPort); ° d ONLN deé <ôw *
? /* make bitmap the size of the bounds that caller supplied */ ° d ONLN d•ò <£ ‹ *
newPort->portRect = *inBounds; ° d ONLN dΔ¢ <≠ ˇ *
' newPort->portBits.bounds = *inBounds; ◊ X◊
*#!Drawing Into an Off-Screen Bitmap (Ï3 ) of 6 ˇd ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘ ,
Courier
° d ONLN d (º *T RectRgn(newPort->clipRgn, inBounds); /* avoid wide-open clipRgn, to be safe */ ° d ONLN d U ' 2º *
T RectRgn(newPort->visRgn, inBounds); /* in case newBounds is > screen bounds */ ° d ONLN d ™ ; F≠ *Q /* rowBytes is size of row, it must be rounded up to an even number of bytes */ ° d ONLN d ¸ E P∑ *
S newPort->portBits.rowBytes = ((inBounds->right - inBounds->left + 15) >> 4) << 1; ° d ONLN dP Y dN *> /* number of bytes in BitMap is rowBytes * number of rows */ ° d ONLN dè c n≤ *
R /* see notes at end of Technical Note about using _NewHandle rather than _NewPtr ° d ONLN d‚ m x " *
*/ ° d ONLN d w Ç Æ *
newPort->portBits.baseAddr = ° d ONLN d Å å≤ *
R NewPtr(newPort->portBits.rowBytes * (long) (inBounds->bottom - inBounds ° d ONLN dV Å≤ å∑ ( ®–- ° d ONLN dW ã ñ ; ( ≤ 6>top)); ° d ONLN d_ ï †≤ *
R if (MemError()!=noErr) { /* check to see if we had enough room for the bits */ ° d ONLN d≤ ü ™ Ü *
> ClosePort(newPort); /* dump the visRgn and clipRgn */ ° d ONLN d ≥ æ *
4 DisposPtr((Ptr)newPort); /* dump the GrafPort */ ° d ONLN d= Ω »0 *
8 return false; /* tell caller we failed */ ° d ONLN dv « “ 1 *
} ° d ONLN d| — ‹Ä *
H /* since the bits are just memory, let's clear them before we start */ ° d ONLN d≈ € Êô *
M EraseRect(inBounds); /* OpenPort did a SetPort(newPort) so we are ok */ ° d ONLN d  ö *
*newOffscreen = newPort; ° d ONLN d. Ô ˙ | *
SetPort(savePort); ° d ONLN dC ˘ D *
< return true; /* tell caller we succeeded! */ ° d ONLN dÄ *
}
° d ONLN dÇ %∞ *YHere is the function to get rid of an off-screen bitmap created by the previous function:
° d ONLN d‹1 <
*1void DestroyOffscreenBitMap(GrafPtr oldOffscreen) ° d ONLN d; F *
{ ° d ONLN dE P≤ *
R ClosePort(oldOffscreen); /* dump the visRgn and clipRgn */ ° d ONLN dcO Zl *
D DisposPtr(oldOffscreen->portBits.baseAddr); /* dump the bits */ ° d ONLN d®Y dl *
D DisposPtr((Ptr)oldOffscreen); /* dump the port */ ° d ONLN dÌc n *
}
° d ONLN dÔy Öè *HNow that you know how to create and destroy an off-screen bitmap, let’s ° d ONLN d7yèÖ⁄ (°≠go through the ° d ONLN dFÜ í^ (Æ 6Dmotions of using one. First, let’s define a few things to make the ° d ONLN däÖ^ë§ (Æ|
_NewWindow ° d ONLN dîÜ§íº )F call ° d ONLN döܺí⁄ )a little ° d ONLN d£í û ; (∫ 6clearer.
° d ONLN d¨™ µ ã *#define kIsVisible true ° d ONLN dƒ¥ ø ã *
#define kNoGoAway false ° d ONLN d‹æ … ü *
#define kNoWindowStorage 0L ° d ONLN d¯» ” ÷ *
&#define kFrontWindow ((WindowPtr) -1L)
° d ONLN d fi Í ± *!Here’s the body of the test code:
° d ONLN dAˆ 6 *main() ° d ONLN dH *
{ ° d ONLN dJ
0 *
8 char* myString = "\pThe EYE"; /* string to display */ ° d ONLN dÉ )D *< GrafPtr offscreen; /* our off-screen bitmap */ ° d ONLN d¿( 3S *
? Rect ovalRect; /* used for example drawing */ ° d ONLN d 2 =: *
: Rect myWBounds; /* for creating window */ ° d ONLN d;< G£ *
O Rect OSRect; /* portRect and bounds for off-screen bitmap*/ ° d ONLN dãF Q Å *
WindowPtr myWindow; ° d ONLN d°Z eN *> InitToolbox(); /* exercise for the reader */ ° d ONLN d‡d oN *
> myWBounds = qd.screenBits.bounds; /* size of main screen */ ° d ONLN d n y5 *
9 InsetRect(&myWBounds, 50,50); /* make it fit better */ ° d ONLN d Yx É≠ *
Q myWindow = NewWindow(kNoWindowStorage, &myWBounds, "\pTest Window", kIsVisible, ° d ONLN d ´Ç çb *
B noGrowDocProc, kFrontWindow, kNoGoAway, 0); ° d ONLN d Óå óX *
@ if (!CreateOffscreenBitMap(&offscreen, &myWindow->portRect)) { ° d ONLN d
/ñ ° c *
SysBeep(1); ° d ONLN d
?† ´ r *
ExitToShell(); ◊ 4◊˘
*%4 ) of 6 (Ïj!Drawing Into an Off-Screen Bitmap ˇ. ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +Z-Developer Support Center ( -Û June 1990 / X / ,
Courier
° d ONLN d < ( U ( D Z } ° d ONLN d ' < 2' *
/ /* Example drawing to our off-screen bitmap*/ ° d ONLN d 6 1 < < • *
SetPort(offscreen); ° d ONLN d L ; < F« *
O OSRect = offscreen->portRect; /* offscreen bitmap's local coordinate rect */ ° d ONLN d ú E < P † *
ovalRect = OSRect; ° d ONLN d ± O < Z ‹ *
FillOval(&ovalRect, qd.black); ° d ONLN d “ Y < d “ *
InsetRect(&ovalRect, 1, 20); ° d ONLN d Ò c < n ‹ *
FillOval(&ovalRect, qd.white); ° d ONLN d m < x “ *
InsetRect(&ovalRect, 40, 1); ° d ONLN d1 w < Ç ‹ *
FillOval(&ovalRect, qd.black); ° d ONLN dR Å < åü *
G MoveTo((ovalRect.left + ovalRect.right - StringWidth(myString)) >> 1, ° d ONLN dö ã < ñE *
DrawString(myString); ° d ONLN d¸ ≥ < æà *P /* copy from the off-screen bitmap to the on-screen window. Note that in this ° d ONLN dM Ω < »∏ *
L case the source and destination rects are the same size and both cover the ° d ONLN dö « < “≥ *
K entire area. These rects are allowed to be portions of the source and/or ° d ONLN dÊ — < ‹— *
Q destination and do not have to be the same size. If they are not the same size ° d ONLN d8 € < Ê" *
. then _CopyBits scales the image accordingly. ° d ONLN dg  < P *
*/ ° d ONLN dl Ô < ˙ † *
SetPort(myWindow); ° d ONLN dÅ ˘ <O *
7 CopyBits(&offscreen->portBits, &(*myWindow).portBits, ° d ONLN dπ <ï *
E &offscreen->portRect, &(*myWindow).portRect, srcCopy, 0L); ° d ONLN dˇ <"§ *H DestroyOffscreenBitMap(offscreen); /* dump the off-screen bitmap */ ° d ONLN dH! <,§ *
H while (!Button()); /* give user a chance to see our work of art */ ° d ONLN dë+ <6 A *
}
° d ONLN dìM <\ Ä *&Comments
° d ONLN dúi <u ‰ *%In the example code, the bits of the ° d ONLN d¡h ‰t )®BitMap ° d ONLN d«iu§ )*! structure, which are pointed to ° d ONLN dËi§uΔ )ñby the ° d ONLN dÔhΔt˛ )"baseAddr ° d ONLN d¯v <Ç ± (û Zfield, are allocated by a ° d ONLN du ±Å ‚ )u_NewPtr ° d ONLN dv ‚Çå )1% call. If your off-screen bitmap is ° d ONLN d>våDz )™close to the size of the ° d ONLN dWÇ <éS (™ Z:screen, then the amount of memory needed for the bits can ° d ONLN dëÇSé˛ (™q#be quite large (on the order of 20K ° d ONLN dµé <öE (∂ Z8for the Macintosh SE or 128K for a large screen). This ° d ONLN dÌéEö˛ (∂c%is quite a lot of memory to lock down ° d ONLN dö <¶ Í (¬ Z'in your heap and it can easily lead to ° d ONLN d:ö Ͷ˛ )Æ9fragmentation if you intend to keep the off-screen bitmap ° d ONLN dt¶ <≤⁄ (Œ ZXaround for any length of time. One alternative that lessens this problem is to get the ° d ONLN dö⁄≤˛ (Œ¯bits via ° d ONLN d’≤ <æ Ç (€ Z
_NewHandle ° d ONLN dfl≥ Çø• )F6 so the Memory Manager can move them when necessary. ° d ONLN d≥•ø˛ (€√To implement this ° d ONLN d'¿ <à ¢ (Ë Zapproach, you need ° d ONLN d:¿ ¢Ãc )f%to keep the handle separate from the ° d ONLN d_øcÀõ )¡GrafPort ° d ONLN dg¿õÃ˛ )8 (for example, in a ° d ONLN d{Õ <Ÿ | (ı Zstructure that ° d ONLN däÕ |Ÿ ∂ )@ combines a ° d ONLN dïà ∂ÿ Ó ):GrafPort ° d ONLN dùÕ ÓŸ )8 and a ° d ONLN d§Ãÿ: )"Handle ° d ONLN d™Õ:Ÿ˛ )*'). When you want to use the off-screen ° d ONLN d“⁄ <Ê7 ( Z2bitmap you would then lock the handle and put the ° d ONLN d⁄7ÊΔ )˚ dereferenced handle into the ° d ONLN d!ŸΔ² )èbaseAddr ° d ONLN d*Ê <Ú¢ ( ZLfield. When you are not using the off-screen bitmap you can then unlock it. ° d ONLN dw˛ <
 *"This example does not demonstrate ° d ONLN dô˛ Â
W˛ )Opreserve the contents of windows so that after a temporary window or dialog box ° d ONLN d ) <" ˘ (> Z%obscures part of your windows and is ° d ONLN d N ˘"˛ )Ω4then dismissed, you can quickly handle the resulting ° d ONLN d É" <.† (J ZJupdate events without recreating all of the intermediate drawing commands. ° d ONLN d Œ: <Fz *DMake sure you only restore the pixels within the content regions of ° d ONLN d
:zF˛ (bòyour own windows in case ° d ONLN d
+F <R ˇ (n Z%the temporary window partly obscures ° d ONLN d
PF ˇR˛ )√1windows belonging to other applications or to the ° d ONLN d
ÇR <^ Á (z Z$desktop. Another application could ° d ONLN d
¶R Á^˛ )´8change the contents of its windows while they are behind ° d ONLN d
fl^ <jt (Ü Z<your temporary window, so you cannot simply restore all the ° d ONLN d ^tj˛ (Üípixels that were behind the ° d ONLN d 7j <v q (í Z
temporary ° d ONLN d Aj qv˛ )5Mwindow because that would restore the old contents of the other application’s ° d ONLN d èv <Ç õ (û Zwindows. Instead, ° d ONLN d ¢v õDz )_Eyou could keep keep an off-screen bitmap for each of your windows and ° d ONLN d ËÇ <é v (™ Z
*6!Drawing Into an Off-Screen Bitmap (Ï5 ) of 6 ˇ" ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘
° d ONLN d ) | *An alternate method ° d ONLN d | )⁄ )dGis to make a single off-screen bitmap that is as large as the temporary ° d ONLN d \ ) 5û ( Q 6Nwindow and a region that is the union of the content regions of your windows. ° d ONLN d ™ )û 5⁄ ( Qº Before you ° d ONLN d ∂ 5 A ( ] 63display the temporary window, copy the screen into ° d ONLN d È 5 A⁄ )¯*the off-screen bit map using the region as ° d ONLN d A M
( i 62a mask. After the temporary window is dismissed, ° d ONLN dF A
M⁄ )ı)restore the obscured area by copying from ° d ONLN dp M YI ( u 6?the off-screen bit map into a copy of the Window Manager port, ° d ONLN dØ MI Y⁄ ( ug and use the region as a mask. ° d ONLN dŒ Z f ˘ ( Ç 61If the region has the proper shape and location, ° d ONLN dˇ Z ˘ f/ )· it prevents ,
You may also ° d ONLN dÃ3 \?⁄ )DKwant to refer to the OffScreen library (DTS Sample Code #15) which provides ° d ONLN d? K P (g 6 both high- ° d ONLN d#? PK⁄ )8Iand low-level off-screen bitmap support for the 128K and later ROMs. The ° d ONLN dmK W• (s 6QOffSample application (DTS Sample Code #16) demonstrates the use of this library. ° d ONLN dø{ á Ç *0Further Reference: ¶ 4¶˘ ° d ONLN d“à *î . +
• ° d ONLN d‘à <î ç )Inside Macintosh ° d ONLN d‰à çî )Q, Volumes I & IV, QuickDraw ° d ONLN d î *† . (º H• ° d ONLN dî <† ç )Inside Macintosh ° d ONLN dî ç† )Q, Volume V, Color QuickDraw ° d ONLN d.† *¨ . (» H• ° d ONLN d0† <¨
(Ï 66 ) of 6 (Ïj!Drawing Into an Off-Screen Bitmap ˇº ◊# ˇ ˇˇˇˇ # ◊ ° d WORD S † å ° d WORD R… † Ç
/ Z Å#
0Ià:µú9 " { ˇˇˇˇˇˇˇˇ # † ƒ ° d
ONLN f ˛ † å ° d 1drw2 … -·_ Ä ˇˇˇˇˇˇ è ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˙ ó@ † ò , Times
. WIQkWIQk +]BNew Technical Notes † ô ° d drw2 : °„ † ó ° d 1drw2 eÙ Ä ˇˇˇˇˇˇ P ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä E¿ † ò
Ä ( {ïDeveloper Support † ô ° d drw2 : °„ † ó ° d `drw2 - Ô ˇˇˇˇˇˇ K Ô - Z f f Z ° d 1drw2 ¿˙È ˇˇˇˇˇˇ K ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : 0 ° ö ˇÙ Ä † ò
0 ( UÔ † ô ° d drw2 : °„ † ó ° d 1drw2 ÔÊ˙ ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˝Ä † ò
l +& ® † ô ° d drw2 : °„ † ó ° d 1drw2  -¯ y ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä % † ò
BÄ ( Z \ Macintosh † ô ° d drw2 : °„ † ó † ç ° d drw2 D † É ° d WORD † ç
IR . ° d ONLN d { < é Δ ( ® ZOld Style Colors
° d ONLN d ç < ú r *Imaging ° d ONLN d çê ú˛ ( ∏ÆM.IM.OldColors
° d ONLN d ( ® < ¥ t ( – Z Revised by: ° d ONLN d 4 ® Ñ ¥ )HRich “I See Colors” Collyer ° d ONLN d P ®¡ ¥˛ ( –fl August 1990 ° d ONLN d \ ¥ < ¿ q ( ‹ Z Written by: ° d ONLN d h ¥ Ñ ¿L )H'Rich “I See Colors” Collyer & Byron Han ° d ONLN d ê ¥æ ¿˛ ( ‹‹ October 1989 ° d ONLN d ù à < ÿ
( Ù Z*This Technical Note covers limitations of ° d ONLN d « Ã
ÿ˛ )—0the original Macintosh color model (eight-color) ° d ONLN d ¯ ÿ < ‰ \ ( Zwhich ° d ONLN d ˛ ÿ \ ‰ ≠ ) Inside Macintosh ° d ONLN d ÿ ≠ ‰ì )Q,, Volume I-173, QuickDraw does not document. ° d ONLN d; ‰ < · ( ZChanges since October 1989: ° d ONLN dV ‰ · ∏ )•/ Added definitions of the old-style constants. X ° d ONLN dÜ < Û (1 Z"QuickDraw has always been able to ° d ONLN d® Û˛ )∑4deal with color, just on a very limited basis. Most ° d ONLN d› <!) (= Z0applications have not made use of this feature, ° d ONLN d
)!˛ )Ì'since Color QuickDraw-based Macintoshes ° d ONLN d5! <-: (I Z5come with a better color model. There are, however, ° d ONLN dj!:-˛ )˛'a few nice features which come with the ° d ONLN dí- <9\ (U Z>old style color model. With the old style colors, it is easy ° d ONLN d–-\9˛ (Uz to print color on an ImageWriter ° d ONLN dÒ9 <E# (a Z0with a color ribbon. Another advantage is that ° d ONLN d!9#E˛ )Á,developers do not have to write special-case ° d ONLN dNE <Qâ (m ZAcode depending upon whether or not a machine has Color QuickDraw. ° d ONLN dê] <ié *GNow that you are ready to convert to the old style colors, there are a ° d ONLN d◊]éi˛ (Ö¨few things you should ° d ONLN dÌi <u‰ (ë ZYknow about which do not work with old style colors. This Note covers the limitations of ° d ONLN dFi‰u˛ (ëusing ° d ONLN dLu <Åõ (ù ZLold style colors, as well as the best ways to work around these limitations.
° d ONLN dôô <® à *' Limitations
° d ONLN d•¥ <¿ ‚ *$The most obvious limitation is that ° d ONLN d…¥ ‚¿˛ )¶<of only eight colors: black, white, red, green, blue, cyan, ° d ONLN d¿ <Ã" (Ë Z.yellow, and magenta. This limitation is only ° d ONLN d4¿"Ã˙ )Ê(a problem if you want to produce a color ° d ONLN d\¿˙Ã˛ )ÿ- ° d ONLN d]à <ÿı (Ù Z^intensive application; if this describes your application, then you need not read any further ° d ONLN dªÃıÿ˛ (Ùin ° d ONLN dæÿ <‰ k ( Z
this Note. ° d ONLN d… <¸p *EThe next limitation is that off-screen buffers are not very useful. ° d ONLN dp¸˛ (é You can draw into off-screen ° d ONLN d+¸ <£ ($ ZKbuffers, but there is no way to get the colors back from the buffer. This ° d ONLN dv¸£˛ ($¡leads into the next ° d ONLN dä < Æ (1 Zlimitation, which is that ,
Courier ° d ONLN d§ Æ Ì )r _CopyBits ° d ONLN d≠ Ì∏ )?+ cannot copy more than one color at a time. ° d ONLN dŸ" <. Ü (J ZWhen you call ° d ONLN dÁ! Ü- ≈ )J _CopyBits ° d ONLN d" ≈.û )?+ from an off-screen buffer to your window, ° d ONLN d"û.˛ )Ÿyou need to set the ° d ONLN d// <; (W Z/forecolor to the color you want to copy before ° d ONLN d^/;; )‹calling ° d ONLN df.;:z )# _CopyBits ° d ONLN do/z;˛ )? (i.e., to copy a red object, ° d ONLN dç< <H P (d Zcall ° d ONLN dí; PG ‹ )_ForeColor(redColor) ° d ONLN d¶< ‹H∑ )å*). Now when you copy the object, you can ° d ONLN d–<∑H˛ )€
only copy one ° d ONLN dfiH <T
(p Z.color. If you copy different colored objects ° d ONLN d H
T˛ )—1at one time, then you have a problem. The result ° d ONLN d>T <`÷ (| ZZof a multicolored copy is that all objects copy in the same color, that of the foreground. ° d ONLN dôl <x0 *5It is possible to work with an off-screen buffer and ° d ONLN dŒl0x˛ )Ù.the old style colors, but it requires a lot of ° d ONLN d˝x <Ñ V († Zextra ° d ONLN d x VÑ˛ )Ywork. Unless the objects are really complex, then it is probably easier to just draw the ° d ONLN d ]Ñ <ê fl (¨ Z"objects directly into your window. ◊ X◊
*@Old Style Colors (Ï1 ) of 3 ˇ ° ¿Ù%%DSIDICT:_cv
currentdict /bu known {bu}if
userdict /_cv known not{userdict /_cv 30 dict put}if
_cv begin
/bdf{bind def}bind def
currentscreen/cs exch def/ca exch def/cf exch def
/setcmykcolor where{/setcmykcolor get /cvcmyk exch def}{/cvcmyk{1 sub 4 1 roll 3{3 index add neg dup 0 lt{pop 0}if 3 1 roll}repeat setrgbcolor pop}bdf }ifelse
/ss{//cf //ca //cs setscreen}bdf
/stg{ss setgray}bdf
/strgb{ss setrgbcolor}bdf
/stcmyk{ss cvcmyk}bdf
/min1{dup 0 eq{pop 1}if}bdf
end
currentdict /bn known {bn}if
† øÿ ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘
° d ONLN d ) */One other limitation does exist. Consider the ° d ONLN d / )⁄ )ÿ-following code sample. One would assume that ° d ONLN d ] ) 5 √ ( Q 6$this sample would work at all times. ,
Courier
° d ONLN d Ç A L Å * SetPort (myPort); ° d ONLN d ò K V ≥ *
savedFG := myPort^.fgColor; ° d ONLN d ∏ U `5 *
9 ForeColor (redColor); {or any other color} ° d ONLN d Ú i t à *$ {...drawing takes place here...} ° d ONLN d } à ê * ForeColor (savedFG);
° d ONLN d0 î †7 *=Surprise. It does not always work. The saved value for the ° d ONLN dm ì7 üh ( ºUfgColor ° d ONLN dt îh †ê )1
field of ° d ONLN d~ îê †¢ )(the ° d ONLN dÇ ì¢ ü⁄ )GrafPort ° d ONLN dã ° ≠ Œ ( … 6(is not a classic QuickDraw color if the ° d ONLN d≥ † Œ ¨ )∂GrafPort ° d ONLN dª ° ≠C )8 is actually a ° d ONLN d †C ¨Ç )= CGrafPort ° d ONLN d” °Ç ≠º )?. If dealing ° d ONLN d· °º ≠⁄ ):with a ° d ONLN dË ≠ π W ( ÷ 6 CGrafPort ° d ONLN dÒ Æ W ∫ q )?, the ° d ONLN d˜ ≠ q π ¢ )fgColor ° d ONLN d˛ Æ ¢ ∫$ )1 field actually contains the ° d ONLN d Æ$ ∫⁄ )Ç%foreground color’s entry in the color ° d ONLN dA ª « ó ( „ 6 table, so the second call to ° d ONLN d^ ∫ ó Δ › )
_ForeColor ° d ONLN dh ª › «R )F really messes things up. ° d ONLN dÇ ‘ ‡ ¿ ( ¸ 6$The proper way to set and reset the ° d ONLN d¶ ‘ ¿ ‡î )®*foreground color with classic QuickDraw’s ° d ONLN d– ”î fl⁄ )‘
_ForeColor ° d ONLN d€ ‡ Ï j ( 6call is as follows:
° d ONLN dÔ ¯ Å * SetPort (myPort); ° d ONLN d
≥ *
savedFG := myPort^.fgColor; ° d ONLN d% 5 *
9 ForeColor (redColor); {or any other color} ° d ONLN d_ + à *$ {...drawing takes place here...} ° d ONLN dÑ4 ?ä *J myPort^.fgColor := savedFG; {manually stuff the old fgColor back} ° d ONLN dœ> I£ *
O If (32BQD = TRUE) Then {32BQD is a flag which is made and set by} ° d ONLN d H S≤ *
R PortChanged (myPort); {the application; to set it, the application} ° d ONLN drR ]∑ *
S {needs to check _Gestalt for 32-Bit QuickDraw}
° d ONLN dΔi u ≈ *&This Note also applies to the routine ° d ONLN dÏh ≈t )≠
_BackColor ° d ONLN dˆi u )F.
° d ONLN d¯ç ú j (∏ 6
What Works
° d ONLN d® ¥ Q * The easiest ° d ONLN d® Q¥⁄ )9Lway to work with these limited colors is to use pictures. When you draw the ° d ONLN d\¥ ¿≠ (‹ 6Oimages, you should draw into a picture. Then when you want to draw the images ° d ONLN d´¥≠¿⁄ (‹À into your ° d ONLN dµ¡ Õ ¢ (È 6 window or to a printer, call ° d ONLN d“¿ ¢Ã ˆ )ä _DrawPicture ° d ONLN dfi¡ ˆÕπ )T). Pictures work well with the old style ° d ONLN d¡πÕ⁄ )√colors, ° d ONLN dÕ Ÿå (ı 6Land you don’t need to worry about making sure that the forecolor is current ° d ONLN d[ÕåŸ⁄ (ı™
when you draw ° d ONLN diŸ  q ( 6into your window. ° d ONLN d{Ò ˝ H * Once you ° d ONLN dÑÒ H˝⁄ )0Uhave the picture, you can use it to draw into the screen or to the printer port. You ° d ONLN d⁄˛
A (& 6 can also ° d ONLN d„˛ A
d ))set the ° d ONLN dν d ∏ )# WindowRecord ° d ONLN d˜˛ ∏
¡ )Ts ° d ONLN d˘˝ ¡ ) windowPic ° d ONLN d˛
H )? to equal your ° d ONLN d˝H £ )H
PictureHandle ° d ONLN d ˛£
⁄ )[ so updates ° d ONLN d*
(2 6"are handled by the Window Manager.
° d ONLN dM. =$ *'#What Do Those Constants Mean Anyway
° d ONLN dqI U È *,Each of the constants contains nine bits of ° d ONLN dùI ÈU⁄ )—0information, and each bit has a special meaning. ° d ONLN dœU aM (} 6DFigure 1 illustrates the meaning of each of the bits, while Table 1 ° d ONLN dUMa⁄ (}kshows how each of the color ° d ONLN d/a m Δ (â 6(constants fills in the appropriate bits. ◊ 4◊˘
*c2 ) of 3 (Ï¥Old Style Colors ˇF ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +Z-Developer Support Center ( -Ë August 1990 / X / †09 † Ç
@ ˜ 0 @ @ ˜ ê @ @ ˜ ëåH @ ˜ RP @ ˜ ë–` @ ˜ íP` @ ˜ íRP @ ˜ ÃH @ Ó
@ Ó
@ Ó
@ Ó
@ Û @ Û Ä @ Û ò‡ @ Û • @ Û = @ Û
! @ Û % @ Û ò‡ @ Ó
@ Î @ Î @ Î @ Ò ¸ @ Ò Ä˝ @ Ò
c @ Ò
îí @ Ò
ê˜í @ Ò
êÑ @ Ò
êîí @ Ò
c @ Î @ Ë Ë Ë Ë
Ì yIJ
Ì DIJ
Ì Dâ0
Ì xâH
Ì Dâx
Ì Dâ@
Ì DâH
Ì xá0 Ë Ë Â Â Â Â Ù @ı ˙ ¸ áò ` $˛ ˙ ¸ ÑH Ä"$˛ ˙ âã1ÅHΔ$ù¿G3òé ˙ äLJAâ)(HÄDë$I ˙ S»3¡HË0ÚHÄDë<‚I ˙ R
I(0HÄÑë I ˙ "HJ@ÑI)(HÄÑë$I ˙ !à1ÄáàÊ$àÑÑêòâ
Ù @¸ ˘ Ó ˘ „ „ „ „ „ „ Ò Äı @˜ 0 @ à 3 ˜ ê ê @ D ˜ ìv1ëåH í9ú¿ Ó˜ TòIIRPí ™$â D˜ TêI9ë–a‰í ™$âÁíD˜ 4êIIíP`í D$â D˜ 4êIIíRPí D$â D ˜ I9ÃH D$Ñ¿ D Ò Ä¸ ˚ @Î @˙ † É
IR
° d ONLN dˇˇ ( · ıFigure 1–Bit Definitions
° d ONLN dˇˇ ( πblack ° d ONLN dˇˇ ),white ° d ONLN dˇˇ )4red ° d ONLN dˇˇ )'green ° d ONLN dˇˇ )/blue ° d ONLN dˇˇ )-cyan ° d ONLN dˇˇ )$magenta ° d ONLN dˇˇ )0yellow ° d ONLN dˇˇ ( º(33) ° d ONLN dˇˇ )-(30) ° d ONLN dˇˇ )*(209) ° d ONLN dˇˇ )-(329) ° d ONLN dˇˇ )-(389) ° d ONLN dˇˇ )-(269) ° d ONLN dˇˇ )-(149) ° d ONLN dˇˇ )'(89) | ° d ONLN dˇˇ ( ~Cyan ° d ONLN dˇˇ )E0 ° d ONLN dˇˇ )-0 ° d ONLN dˇˇ )-0 ° d ONLN dˇˇ )-1 ° d ONLN dˇˇ )-1 ° d ONLN dˇˇ )(1 ° d ONLN dˇˇ )20 ° d ONLN dˇˇ ) 0 ° d ONLN dˇˇ (' ~Magenta ° d ONLN dˇˇ )E0 ° d ONLN dˇˇ )-0 ° d ONLN dˇˇ )-1 ° d ONLN dˇˇ )-0 ° d ONLN dˇˇ )-1 ° d ONLN dˇˇ )(0 ° d ONLN dˇˇ )21 ° d ONLN dˇˇ ) 0 ° d ONLN dˇˇ (2 ~Yellow ° d ONLN dˇˇ )E0 ° d ONLN dˇˇ )-0 ° d ONLN dˇˇ )-1 ° d ONLN dˇˇ )-1 ° d ONLN dˇˇ )-0 ° d ONLN dˇˇ )(0 ° d ONLN dˇˇ )20 ° d ONLN dˇˇ ) 1 ° d ONLN dˇˇ (= ~Black ° d ONLN dˇˇ )E1 ° d ONLN dˇˇ )-0 ° d ONLN dˇˇ )-0 ° d ONLN dˇˇ )-0 ° d ONLN dˇˇ )-0 ° d ONLN dˇˇ )(0 ° d ONLN dˇˇ )20 ° d ONLN dˇˇ ) 0 ° d ONLN dˇˇ (H ~Red ° d ONLN dˇˇ )E0 ° d ONLN dˇˇ )-1 ° d ONLN dˇˇ )-1 ° d ONLN dˇˇ )-0 ° d ONLN dˇˇ )-0 ° d ONLN dˇˇ )(0 ° d ONLN dˇˇ )21 ° d ONLN dˇˇ ) 1 ° d ONLN dˇˇ (S ~Green ° d ONLN dˇˇ )E0 ° d ONLN dˇˇ )-1 ° d ONLN dˇˇ )-0 ° d ONLN dˇˇ )-1 ° d ONLN dˇˇ )-0 ° d ONLN dˇˇ )(1 ° d ONLN dˇˇ )20 ° d ONLN dˇˇ ) 1 ° d ONLN dˇˇ (^ ~Blue ° d ONLN dˇˇ )E0 ° d ONLN dˇˇ )-1 ° d ONLN dˇˇ )-0 ° d ONLN dˇˇ )-0 ° d ONLN dˇˇ )-1 ° d ONLN dˇˇ )(1 ° d ONLN dˇˇ )21 ° d ONLN dˇˇ ) 0 ° d ONLN dˇˇ (i ~Inverse ° d ONLN dˇˇ )E0 ° d ONLN dˇˇ )-1 ° d ONLN dˇˇ )-0 ° d ONLN dˇˇ )-0 ° d ONLN dˇˇ )-0 ° d ONLN dˇˇ )(0 ° d ONLN dˇˇ )20 ° d ONLN dˇˇ ) 0 ° d ONLN dˇˇ (t ~Normal ° d ONLN dˇˇ )E1 ° d ONLN dˇˇ )-0 ° d ONLN dˇˇ )-1 ° d ONLN dˇˇ )-1 ° d ONLN dˇˇ )-1 ° d ONLN dˇˇ )(1 ° d ONLN dˇˇ )21 ° d ONLN dˇˇ ) 1 v |v
° d ONLN dˇˇ (å  Table 1–Color-Bit Correlation ° d ONLN dˇˇ (º ZFurther Reference: ø Xø ° d ONLN dˇˇ +
• ° d ONLN dˇˇ )Inside Macintosh ° d ONLN dˇˇ )Q, Volume I-173, QuickDraw ° d ONLN dˇˇ (’ l• ° d ONLN dˇˇ ) Technical Note M.IM.Copybits — ° d ONLN dˇˇ +$ Of Time and Space and _CopyBits ◊ X◊
ONLN f ˛ † å ° d 1drw2 … -·_ Ä ˇˇˇˇˇˇ è ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˙ ó@ † ò , Times
. R… R… +]BNew Technical Notes † ô ° d drw2 : °„ † ó ° d 1drw2 eÙ Ä ˇˇˇˇˇˇ P ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä E¿ † ò
( {ïDeveloper Support † ô ° d drw2 : °„ † ó ° d `drw2 - Ô ˇˇˇˇˇˇ K Ô - Z f f Z ° d 1drw2 ¿˙È ˇˇˇˇˇˇ K ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : 0 ° ö ˇÙ Ä † ò
0 ( UÔ † ô ° d drw2 : °„ † ó ° d 1drw2 ÔÊ˙ ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˝Ä † ò
+& ® † ô ° d drw2 : °„ † ó ° d 1drw2  -¯ y ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä % † ò
( Z \ Macintosh † ô ° d drw2 : °„ † ó † ç ° d drw2 D † É
IR . ° d ONLN d z < çΔ ( ß Z*Things You Wanted to Know About _PackBits* ° d ONLN d , å r üA +6*But Were Afraid to Ask
° d ONLN d D û < ≠ r ( … ZImaging ° d ONLN d L ûõ ≠˛ ( …π
M.IM.PackBits
° d ONLN d Z π < ≈ t ( · Z Revised by: ° d ONLN d f π Ñ ≈] )H,Guillermo Ortiz, Jon Zap, and Forrest Tanaka ° d ONLN d ì πæ ≈˛ ( ·‹ January 1992 ° d ONLN d † ≈ < — q ( Ì Z Written by: ° d ONLN d ¨ ≈ Ñ — À )H
Cameron Birse ° d ONLN d ∫ ≈± —˛ ( Ìœ
November 1987 ° d ONLN d » fi < Ír ( Z?This Technical Note describes the format of data packed by the ° d ONLN d fir Íø (êToolbox utility ,
Courier ° d ONLN d ›ø È˛ )M _PackBits ° d ONLN d! Î < ˜ ’ ( Z and documents a change to the ° d ONLN d? Í ’ ˆ
)ôsrcBytes ° d ONLN dG Î
˜â )8 limit and possible worst ° d ONLN da Îâ ˜˛ )|case. Although you can ° d ONLN dx ¯ < ⁄ ( Z simply unpack this data using ° d ONLN dñ ˜ ⁄' )û _UnPackBits ° d ONLN d° ¯'˛ )M), Apple provides this information for the ° d ONLN dÀ <A (- Z6terminally curious and for those manipulating MacPaint
° d ONLN dAH (*_®
° d ONLN dHÏ +! documents or PICT files by hand. ° d ONLN d% < t (9 Z Warning: ° d ONLN d. t H )8-This format information is subject to change. ° d ONLN d\ <) Ô (E Z Changes since November 1990: ° d ONLN dx Ô): )≥ A warning has ° d ONLN dá :)˙ )K'been added about the handling of a flag ° d ONLN dÆ ˙)˛ )¿- ° d ONLN dØ) <5 º (Q Zcounter byte value of -128. ` X`
° d ONLN dÀZ <i “ *4Length Doesn’t Matter
° d ONLN d·v <Ç ] *Inside ° d ONLN dËv ]Ç é )! Macintosh ° d ONLN dÒv éÇô )16, Volume I-470, describes the Pascal interface to the ° d ONLN d'uôÅÿ (û∑ _PackBits ° d ONLN d0vÿDz )? trap as ° d ONLN d9Ç <é c (™ Zfollows:
° d ONLN dBö <•| *@ PROCEDURE PackBits(VAR srcPtr,dstPtr:Ptr; srcBytes:INTEGER);
° d ONLN dɱ <Ω ò *The accompanying ° d ONLN dî± òΩ ‡ )\text states that ° d ONLN d•∞ ‡º )HsrcBytes ° d ONLN d≠±Ω˛ )8., the length of your uncompressed data, should ° d ONLN d‹æ < Ù (Ê Z)not be greater than 127, and that in the ° d ONLN dæ Ù ∑ )∏'worst case, the compressed data can be ° d ONLN d,Ω∑…˛ )√
srcBytes + ° d ONLN d7 <÷ C (Û Z1 ° d ONLN d8À C◊Ó )U. To pack more than 127 bytes, you had to break the data up into 127-byte groups and ° d ONLN dçÀÓ◊˛ (Û call ° d ONLN dí◊ <„ { ( Z _PackBits ° d ONLN dõÿ {‰ ¸ )? on each group. Beginning ° d ONLN dµÿ ¸‰˛ )Å5with system software version 6.0.2, this limit of 127 ° d ONLN dΉ < Î ( Z"bytes is no longer valid. The new ° d ONLN d
‰ β )Ø4limit is 32,767 bytes, which is the maximum positive ° d ONLN dBÒ <˝ } ( Z number that ° d ONLN dN }¸ µ )AsrcBytes ° d ONLN dVÒ µ˝ — )8 can ° d ONLN d[Ò —˝˛ ) 7hold. The worst case can be determined according to the ° d ONLN dì˝ < ï (% Zfollowing formula:
° d ONLN d¶ < ˇ *' (srcBytes + (srcBytes+126) DIV 127)
° d ONLN dŒ+ <7, *1which is comparable to what you would get if you ° d ONLN dˇ+,7˛ )*broke up the data into 127-byte groups and ° d ONLN d*7 <C (_ Z,picked up an additional byte for each group.
° d ONLN dW[ <jW *'$Mommy, How Do They Make Packed Bits?
° d ONLN d|v <Ç› *VThe first byte is a flag-counter byte that specifies whether or not the the following ° d ONLN d“v›Ç˛ (û˚data is ° d ONLN d⁄Ç <é ¥ (™ Zpacked, and the number ° d ONLN dÒÇ ¥é˛ )xDof bytes involved. If this first byte is a negative number, then the ° d ONLN d6é <ö (∂ Z,following data is packed. In this case, the ° d ONLN dbé ö˛ )œ.number is the two’s complement of a zero-based ° d ONLN dëö <¶ z (¬ Z
count of the ° d ONLN dûö z¶˛ )>Knumber of times the data byte repeats when expanded. There is one data byte ◊ X◊
(Ï Z)Things You Wanted to Know About _PackBits (Ï1 ) of 4 ˇ ° ¿Ù%%DSIDICT:_cv
currentdict /bu known {bu}if
userdict /_cv known not{userdict /_cv 30 dict put}if
_cv begin
/bdf{bind def}bind def
currentscreen/cs exch def/ca exch def/cf exch def
/setcmykcolor where{/setcmykcolor get /cvcmyk exch def}{/cvcmyk{1 sub 4 1 roll 3{3 index add neg dup 0 lt{pop 0}if 3 1 roll}repeat setrgbcolor pop}bdf }ifelse
/ss{//cf //ca //cs setscreen}bdf
/stg{ss setgray}bdf
/strgb{ss setrgbcolor}bdf
/stcmyk{ss cvcmyk}bdf
/min1{dup 0 eq{pop 1}if}bdf
end
currentdict /bn known {bn}if
† ø$ ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘
° d ONLN d ) Ò *.following this first byte in packed data. The ° d ONLN d . Ò )⁄ )Ÿ1byte after the data byte is the next flag-counter ° d ONLN d ` ) 5 0 ( Q 6byte. ° d ONLN d f A M *8If the flag-counter byte is a positive number, then the ° d ONLN d û A M⁄ )˝)following data is unpacked. In this case, ° d ONLN d » M Yò ( u 6Qthe number is a zero-based count of the number of incompressible data bytes that ° d ONLN d Mò Y⁄ ( u∂
Courier ° d ONLN dï ï °a )¸ _UnPackBits ° d ONLN d† ña ¢æ )M requires the length ° d ONLN dµ ñæ ¢⁄ )]of the ° d ONLN dº ¢ Æ _ ( 6unpacked data. ° d ONLN dÀ ª « L *Warning: ° d ONLN d‘ ∫ ` Δ ü )H _PackBits ° d ONLN d› ª ü « )? never generates the ° d ONLN dÚ ª «∂ )h"value -128 ($80) as a flag-counter ° d ONLN d « ` ”3 ( Ô ~'byte, but a few PackBits-like routines ° d ONLN d< «3 ”∂ )”that are built into some ° d ONLN dU ‘ ` ‡ Æ ( ¸ ~applications do. ° d ONLN df ” Æ fl ˚ )N _UnpackBits ° d ONLN dq ‘ ˚ ‡∂ )M' handles this situation by skipping any ° d ONLN dô ‡ ` Ï µ ( ~flag-counter byte ° d ONLN d´ ‡ µ Ï∂ )U5with this value and interpreting the next byte as the ° d ONLN d· Ï ` ¯i ( ~3next flag-counter byte. If you’re writing your own ° d ONLN d Ïi ¯∂ (áUnpackBits-like ° d ONLN d$ ¯ `z ( ~=routine, make sure it handles this situation in the same way. ° d ONLN db ≤ (8 6 Consider the following example: ° d ONLN dÇ( 4 a *Unpacked data:
° d ONLN dë@ Kè *K AA AA AA 80 00 2A AA AA AA AA 80 00 2A 22 AA AA AA AA AA AA AA AA AA AA
° d ONLN d›W c É *After being packed by ° d ONLN dÛV Éb ¬ )k _PackBits ° d ONLN d¸W ¬c ≈ )?:
° d ONLN d˛o zq (ñ 6E FE AA ; (-(-2)+1) = 3 bytes of the pattern $AA ° d ONLN dDy ÑS *
? 02 80 00 2A ; (2)+1 = 3 bytes of discrete data ° d ONLN dÑÉ éq *
E FD AA ; (-(-3)+1) = 4 bytes of the pattern $AA ° d ONLN d ç òS *
? 03 80 00 2A 22 ; (3)+1 = 4 bytes of discrete data ° d ONLN d
ó ¢v *
F F7 AA ; (-(-9)+1) = 10 bytes of the pattern $AA
° d ONLN dQ≠ π 7 * or
° d ONLN d[≈ – *0 FE AA 02 80 00 2A FD AA 03 80 00 2A 22 F7 AA ° d ONLN dåœ ⁄ Ù *
packs the ° d ONLN dÚ ˛ } ( 6data only when there ° d ONLN d)Ú }˛⁄ )eIare three or more consecutive bytes with the same data; otherwise it just ° d ONLN ds˛
(& 68copies the data byte for byte (and adds the count byte). ° d ONLN d¨ # 7 *Note: ° d ONLN d≤ <# Ò )$#The data associated with some PICT ° d ONLN d’ Ò#H )µopcodes, $0098 ( ° d ONLN dÂH"ú )W PackBitsRect ° d ONLN dÒú#∂ )T) and ° d ONLN d˜$ <0 a (L Z$0099 ° d ONLN d˝$ a0 e )%( ° d ONLN d˛# e/ ≤ ) PackBitsRgn ° d ONLN d $ ≤0 Ï )M ), contain ° d ONLN d# Ï/ ):PixData ° d ONLN d$ 0∂ )1 which is basically made of ° d ONLN d70 << { (Y Z _PackBits ° d ONLN d@1 {= ÿ )? data. It should be ° d ONLN dT1 ÿ=Ö )]#noted, though, that the format for ° d ONLN dw0Ö<∂ )≠PixData ° d ONLN d> <J n (f Z includes a ° d ONLN dä= nI ≠ )2 byteCount ° d ONLN dì> ≠J∞ )?: or length in addition to the data described in this Note. ° d ONLN dŒV b_ (~ 6DFor example, the following is the result of decoding a sample PICT2:
° d ONLN d n y Å *data 'PICT' (25534) { ° d ONLN d )x Él *
D 0936 0000 0000 0007 001E /* pic size, picFrame */ ° d ONLN d nÇ çl *
D 0011 02FF /* pict2 */ ° d ONLN d ≥å ól *
D 0C00 /* header */ ° d ONLN d ¯ñ °l *
D FFFF FFFF 0000 0000 0000 0000 001E 0000 0007 0000 0000 0000 ° d ONLN d
=† ´l *
D 001E /* def hilite */ ◊ 4◊˘
*%2 ) of 4 (Ï;)Things You Wanted to Know About _PackBits ˇfi ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +Z-/Developer Support Center ( -Á January 1992 / X / ,
Courier
° d ONLN d < (ê ( D ZD 0001 /* clipRgn */ ° d ONLN d E ' < 2 · *
! 000A 0000 0000 0007 001E ° d ONLN d g 1 < <ê *
D 0098 /* PackBitsRect */ ° d ONLN d ¨ ; < Fê *
D 801E /* rowbytes of 30 */ ° d ONLN d Ò E < Pê *
D 0000 0000 0007 001E /* Bounds */ ° d ONLN d6 O < Zê *
> /* line 6, byte count is 18 */ ° d ONLN d3! , O *
12 ° d ONLN d?+ 6N *
> 00 FF /* 1 data byte */ ° d ONLN d~5 @N *
> FC 23 /* 5 0x23's */ ° d ONLN dΩ? JN *
> FE 00 /* 3 0's */ ° d ONLN d¸I TN *
> FC 23 /* 5 0x23's */ ° d ONLN d;S ^N *
> FE 00 /* 3 0's */ ° d ONLN dz] hN *
> FC 23 /* 5 0x23's */ ° d ONLN dπg rN *
> FE 00 /* 3 0's */ ° d ONLN d¯q |N *
> FD 23 /* 4 0x23's */ ° d ONLN d7{ ÜN *
> 00 FF /* 1 data byte */ ° d ONLN dvÖ êN *
> /* line 7, byte count is 2 (best case for a row) */ ° d ONLN dµè ö O *
02 ° d ONLN d¡ô §N *
> E3 FF /* 30 0xFF's */ ° d ONLN d £ ÆN *
> 00 /* pad so next command starts at word boundary */ ° d ONLN d ?∑ ¬N *> 00FF /*end of pic */ ° d ONLN d ~¡ Ã " *
};
° d ONLN d ÅÔ ˚ Ç */Further Reference: 4˘ ° d ONLN d î¸ * . +
• ° d ONLN d ñ¸ < ç )Inside Macintosh ° d ONLN d ¶¸ çB )Q%, Volume I-465, The Toolbox Utilities ° d ONLN d à * . (0 H• ° d ONLN d Œ < ç )Inside Macintosh ° d ONLN d fi ç/ )Q , Volume V-39, Color QuickDraw ° d ONLN d ˝ * . (< H• ° d ONLN d ˇ < Ù )!Technical Note M.PT.MacPaintDoc — ° d ONLN d
# `, Á +$ MacPaint Document Format ° d ONLN d
=, *8 ‹ (T H&MacPaint is a registered trademark of ° d ONLN d
c, ‹8 ‰ )≤C
° d ONLN d
d, ‰8 )LARIS
° d ONLN d
i,8A )
Corporation. ◊ 4◊˘
(Ï 64 ) of 4 (Ï;)Things You Wanted to Know About _PackBits ˇ ◊# ˇ ˇˇˇˇ # ◊ † Ç
/ Z Å#
0Ià:µú9 " { ˇˇˇˇˇˇˇˇ # † ƒ ° d
ONLN f ˛ † å ° d 1drw2 … -·_ Ä ˇˇˇˇˇˇ è ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˙ ó@ † ò , Times
. R… R… +]BNew Technical Notes † ô ° d drw2 : °„ † ó ° d 1drw2 eÙ Ä ˇˇˇˇˇˇ P ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä E¿ † ò
( {ïDeveloper Support † ô ° d drw2 : °„ † ó ° d `drw2 - Ô ˇˇˇˇˇˇ K Ô - Z f f Z ° d 1drw2 ¿˙È ˇˇˇˇˇˇ K ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : 0 ° ö ˇÙ Ä † ò
0 ( UÔ † ô ° d drw2 : °„ † ó ° d 1drw2 ÔÊ˙ ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˝Ä † ò
+& ® † ô ° d drw2 : °„ † ó ° d 1drw2  -¯ y ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä % † ò
( Z \ Macintosh † ô ° d drw2 : °„ † ó † ç ° d drw2 D † É
IR . ° d ONLN d z < çï ( ß Z'Palette Manager Changes in System 6.0.2
° d ONLN d ( å < õ r *Imaging ° d ONLN d 0 å8 õ˛ )¸M.IM.PaletteManagerChanges
° d ONLN d K ß < ≥ q ( œ Z Written by: ° d ONLN d W ß Ñ ≥ Œ )HGuillermo Ortiz ° d ONLN d g ßæ ≥˛ ( œ‹ October 1988 ° d ONLN d t ø < Àl ( Á Z>This Technical Note describes the changes and enhancements to ° d ONLN d ≤ øl À˛ ( Áä the Palette Manager in System ° d ONLN d – À < ◊ Ê ( Û Z#Software 6.0.2 and future versions. X
'pltt' ID ° d ONLN d[ß ⁄≥ ¯ )F= 0 ° d ONLN d_® ¯¥˛ ) 8resource and uses the palette which it contains. If the ° d ONLN dò¥ <¿ ` (‹ Zsystem ° d ONLN dü¥ `¿˛ )$Ycannot find this resource in the application’s resource fork, it will use its own default ° d ONLN d˘¡ <Õ å (È Zpalette (resource ° d ONLN d ¿ åÃ Ó )P'pltt' ID = 0 ° d ONLN d¡ ÓÕQ )bin the System file) if ° d ONLN d0¡QÕ˛ )c&present, or, if necessary, it will use ° d ONLN dWÕ <Ÿ Î (ı Z'the Palette Manager’s built-in palette. ° d ONLN dÊ <Ú† *>Once an application has set its color environment (by calling ° d ONLN dΩ†ÒÊ (æ
_InitMenus ° d ONLN d«ÊÊÚÙ )F, ° d ONLN d…ÊÙÚ˛ )or ° d ONLN dÃÚ <˛ ó ( Z
_InitPalettes ° d ONLN dŸÛ óˇ ƒ )[
in weird ° d ONLN d„Û ƒˇ˛ )-Binstances when there are no menus) it can find the default palette ° d ONLN d& < o (( Z by calling ° d ONLN d1ˇ o > )3 GetPalette ( WindowPtr (-1) ) ° d ONLN dN > ´ )œ or change the default ° d ONLN de ´ ˛ )mpalette by calling ° d ONLN dx <£ (5 Z/SetPalette ( WindowPtr (-1), newDefPltt, true ) ° d ONLN dß
£÷ (5¡. Note ° d ONLN dØ
÷˛ )3that the ° d ONLN d∏ <& ñ (B Zinitialization of the ° d ONLN dŒ ñ&) )Z Palette Manager with a call to ° d ONLN dÌ)%o )ì
_InitMenus ° d ONLN d˜o&· )F is contrary to the way ° d ONLN d·&˛ )rInside ° d ONLN d& <2 m (N Z Macintosh ° d ONLN d & m2N )1-, Volume V, The Palette Manager documents it.
° d ONLN dMJ <Y fi (u ZOne Palette, Many Ports
° d ONLN def <r Ñ * You can now ° d ONLN dqf Ñr* )H associate one palette with many ° d ONLN dëe*qi )¶ CGrafPort ° d ONLN döfirÜ )? and ° d ONLN düeÜq∑ ) CWindow ° d ONLN d¶f∑r˛ )1 records, thus ° d ONLN dµr <~ ¶ (ö Zsimplifying the use of ° d ONLN dÃr ¶~˛ )jEa single palette with multiple ports and windows; System Software 6.0 ° d ONLN d~ <äè (¶ ZKand earlier require copies of the palette to use it with different windows. ◊ X◊
*F'Palette Manager Changes in System 6.0.2 (Ï1 ) of 3 ˇ ° ¿Ù%%DSIDICT:_cv
currentdict /bu known {bu}if
userdict /_cv known not{userdict /_cv 30 dict put}if
_cv begin
/bdf{bind def}bind def
currentscreen/cs exch def/ca exch def/cf exch def
/setcmykcolor where{/setcmykcolor get /cvcmyk exch def}{/cvcmyk{1 sub 4 1 roll 3{3 index add neg dup 0 lt{pop 0}if 3 1 roll}repeat setrgbcolor pop}bdf }ifelse
/ss{//cf //ca //cs setscreen}bdf
/stg{ss setgray}bdf
/strgb{ss setrgbcolor}bdf
/stcmyk{ss cvcmyk}bdf
/min1{dup 0 eq{pop 1}if}bdf
end
currentdict /bn known {bn}if
† øD ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘
° d ONLN d )O *CAlthough this ability to associate one palette with multiple ports ° d ONLN d C O )⁄ ( Emand windows will allow the ° d ONLN d ^ * 6 P ( R 6
use of calls ° d ONLN d k * P 6 e )8like ,
Courier ° d ONLN d p ) e 5 π ) _PmForeColor ° d ONLN d | * π 6 “ )T and ° d ONLN d Å ) “ 5& ) _PmBackColor ° d ONLN d ç *& 6Q )T
, calling ° d ONLN d ó )Q 5¡ )+_ActivatePalette ° d ONLN d ß *¡ 6⁄ )p with ° d ONLN d ≠ 6 B@ ( ^ 6Ban off-screen port does nothing, and as a result, calling it with ° d ONLN d Ô 6@ B⁄ ( ^^!an off-screen port will associate ° d ONLN d B Né ( j 6Qthe palette with the port but will not cause any change in the color environment. ° d ONLN dc [ g *2One important implication of this feature is that ° d ONLN dï Z f[ )Ë
DisposeWindow ° d ONLN d¢ [[ gd )[ ( ° d ONLN d§ Zd fø )
_DisposWindow ° d ONLN d± [ø g⁄ )[) will ° d ONLN d∏ g s1 ( è 6=not dispose of the associated palette automatically since it ° d ONLN dı g1 s⁄ ( èO"may be allocated to other ports or ° d ONLN d s ƒ ( õ 6Iwindows. The only exception to this behavior is when an application has ° d ONLN da sƒ ⁄ ( õ‚used ° d ONLN df ã z ( ® 6_GetNewCWindow ° d ONLN dt Ä z å )b" to create the window, there is a ° d ONLN dñ ã= )ô'pltt' ° d ONLN dú Ä= åæ )* resource with the same ID ° d ONLN d∑ Äæ å⁄ )Åas the ° d ONLN dæ ç ô ‰ ( µ 6+window, and the application has not called ° d ONLN dÈ å ‰ ò1 )Ã _GetPalette ° d ONLN dÙ ç1 ôÅ )M for the window.
° d ONLN d ± ¿ w ( ‹ 6
Color Updates
° d ONLN d Õ Ÿ *1System version 6.0.2 also introduces a new call, ° d ONLN dD à ÿm ( ı7 _NSetPalette ° d ONLN dP Õm Ÿ⁄ )T, which complements ° d ONLN dd Ÿ  e ( 6 _SetPalette ° d ONLN do ⁄ e Ê s )M. ° d ONLN dr Ÿ s  « ) _NSetPalette ° d ONLN d~ ⁄ « Ê` )T has the same functionality as ° d ONLN dù Ÿ` Â≠ )ô _SetPalette ° d ONLN d® ⁄≠ Ê⁄ )M , but the ° d ONLN d≤ Ê Ú P ( 6CUpdates ° d ONLN d∫ Á P Û ˇ )8$ parameter has been modified from a ° d ONLN dfi Ê ˇ Ú0 )ØBoolean ° d ONLN d Á0 ÛM )1 to an ° d ONLN dÏ ÊM Ú~ ) Integer ° d ONLN dÛ Á~ Ûµ )1 as follows:
° d ONLN d ˇ
{ (& 6GPROCEDURE NSetPalette (dstWindow: WindowPtr; srcPalette: PaletteHandle; ° d ONLN dI < † +$
nCUpdates: INTEGER); ° d ONLN d^ Y (: 6
INLINE $AA95;
° d ONLN dl) 5 l * _NSetPalette ° d ONLN dx* l6 o )T ° d ONLN dy* o6 )$changes the palette associated with ° d ONLN dù)5Y )´ dstWindow ° d ONLN d¶*Y6j )? to ° d ONLN d™)j5∞ )
srcPalette ° d ONLN d¥*∞6⁄ )F
. It also ° d ONLN dø6 B` (^ 6@records whether the window wants to receive updates as a result ° d ONLN dˇ6`B⁄ (^~of a change to its color ° d ONLN dC O ¶ (k 6environment. If you want ° d ONLN d2B ¶N Â )é dstWindow ° d ONLN d;C ÂO Î )? ° d ONLN d<C ÎO⁄ ),to be updated whenever its color environment ° d ONLN diP \ W (x 6
changes, set ° d ONLN dvO W[ ñ )? nCUpdates ° d ONLN dP ñ\ ß )? to ° d ONLN dÉO ß[ ˚ ) pmAllUpdates ° d ONLN dèP ˚\ )T. If ° d ONLN dïP\⁄ )'you are only interested in updates when ° d ONLN dΩ\ h W (Ö 6 dstWindow ° d ONLN dΔ] Wi fi )? is the active window, set ° d ONLN d·\ fih )á nCUpdates ° d ONLN dÍ] i0 )? to ° d ONLN dÓ\0h} ) pmFgUpdates ° d ONLN d˘]}iã )M. ° d ONLN d¸]ãi⁄ )If you are only ° d ONLN d j v § (í 6interested in updates when ° d ONLN d'i §u „ )å dstWindow ° d ONLN d0j „v È )? ° d ONLN d1j Èvã ) is not the active window, set ° d ONLN dOiãu )¢ nCUpdates ° d ONLN dXj v⁄ )? to ° d ONLN d\v Ç e (ü 6 pmBkUpdates ° d ONLN dgw eÉ i )M.
° d ONLN diè ö ∏ (∂ 6 { NSetPalette Update Constants } ° d ONLN dä£ Æ ^ *pmNoUpdates = ° d ONLN dô£ ÑÆ ¢ )l$8000; ° d ONLN d†£ ®Æ ‰ )$ {no updates} ° d ONLN d≠≠ ∏ ^ (‘ 6pmBkUpdates = ° d ONLN dº≠ Ñ∏ ¢ )l$A000; ° d ONLN d√≠ ®∏% )${background updates only} ° d ONLN d›∑ ¬ ^ (fi 6pmFgUpdates = ° d ONLN dÏ∑ Ѭ ¢ )l$C000; ° d ONLN dÛ∑ ®¬% )${foreground updates only} ° d ONLN d
¡ à c (Ë 6pmAllUpdates = ° d ONLN d ¡ Ñà ¢ )l$E000; ° d ONLN d$¡ ®Ã È )$
{all updates}
° d ONLN d2◊ „ e ( 6 _SetPalette ° d ONLN d=ÿ e‰ ¯ )M! retains its syntax and function:
° d ONLN d_ ˚v ( 6FPROCEDURE SetPalette (dstWindow: WindowPtr; srcPalette: PaletteHandle; ° d ONLN dß˙ < õ +$
CUpdates: Boolean); ° d ONLN dª Y (+ 6
INLINE $AA95;
° d ONLN d… ' 7 *Note: ° d ONLN dœ <' ò )$The trap words for ° d ONLN d‚ ò& Ï )\ _NSetPalette ° d ONLN dÓ Ï' )T and ° d ONLN dÛ&P ) _SetPalette ° d ONLN d˛P'S )M ° d ONLN dˇS'a )are ° d ONLN da'è ) identical.
° d ONLN d? N g (j 6 CopyPalette
° d ONLN dZ eI *=PROCEDURE CopyPalette (srcPalette, dstPalette: PaletteHandle; ° d ONLN dYd <o ˙ +$
&srcEntry,dstEntry,dstLength: INTEGER); ° d ONLN dÄn y Y (ï 6
INLINE $AAA1;
° d ONLN déÑ ê l * _CopyPalette ° d ONLN döÖ lë )T$ is a utility procedure that copies ° d ONLN dæÑêF )õ dstLength ° d ONLN d«ÖFëI )? ° d ONLN d»ÖIë⁄ ) entries from the source palette ° d ONLN dËí û (∫ 61into the destination palette; the copy begins at ° d ONLN d ë ù8 )ËsrcEntry ° d ONLN d !í8ûU )8 and ° d ONLN d &ëUùû )
dstEntry, ° d ONLN d 0íûû⁄ )I
respectively. ◊ 4◊˘
(Ï 62 ) of 3 (ÏO'Palette Manager Changes in System 6.0.2 ˇ8 ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +Z-Developer Support Center ( -Ê October 1988 / X / ,
Courier
° d ONLN d < ) ê ( F Z _CopyPalette ° d ONLN d ê *€ )TJ will resize the destination palette when the number of entries after the ° d ONLN d V € *˛ ( F˘copy is ° d ONLN d ^ * < 6 Ø ( R Zgreater than the original. ° d ONLN d y B < N ê * _CopyPalette ° d ONLN d Ö C ê O ƒ )T
(Ï Z'Palette Manager Changes in System 6.0.2 (Ï3 ) of 3 ˇn ◊# ˇ ˇˇˇˇ # ◊ † Ç
/ Z Å#
0Ià:µú9 " { ˇˇˇˇˇˇˇˇ # † ƒ ° d
ONLN f ˛ † å ° d 1drw2 … -·_ Ä ˇˇˇˇˇˇ è ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˙ ó@ † ò , Times
. R… R… +]BNew Technical Notes † ô ° d drw2 : °„ † ó ° d 1drw2 eÙ Ä ˇˇˇˇˇˇ P ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä E¿ † ò
( {ïDeveloper Support † ô ° d drw2 : °„ † ó ° d `drw2 - Ô ˇˇˇˇˇˇ K Ô - Z f f Z ° d 1drw2 ¿˙È ˇˇˇˇˇˇ K ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : 0 ° ö ˇÙ Ä † ò
0 ( UÔ † ô ° d drw2 : °„ † ó ° d 1drw2 ÔÊ˙ ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˝Ä † ò
+& ® † ô ° d drw2 : °„ † ó ° d 1drw2  -¯ y ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä % † ò
( Z \ Macintosh † ô ° d drw2 : °„ † ó † ç ° d drw2 D † É
IR . ° d ONLN dˇˇ ( õ ZPalette Manager Q&As
° d ONLN dˇˇ *Imaging ° d ONLN dˇˇ ( ´|M.IM.PaletteMgr.Q&As
° d ONLN dˇˇ ( √ Z Revised by: ° d ONLN dˇˇ )HDeveloper Support Center ° d ONLN dˇˇ ( √‹ October 1992 ° d ONLN dˇˇ ( œ Z Written by: ° d ONLN dˇˇ )HDeveloper Support Center ° d ONLN dˇˇ ( œ‹ October 1990 ° d ONLN dˇˇ ( Á Z This Technical Note contains a ° d ONLN dˇˇ )û9collection of Q&As relating to a specific topic—questions ° d ONLN dˇˇ ( Û ZGyou’ve sent the Developer Support Center (DSC) along with answers from ° d ONLN dˇˇ ( Ûæthe DSC engineers. ° d ONLN dˇˇ ( ˇ Z
While DSC ° d ONLN dˇˇ )9Lengineers have checked the Q&A content for accuracy, the Q&A Technical Notes ° d ONLN dˇˇ ( Z don’t have ° d ONLN dˇˇ )5Qthe editing and organization of other Technical Notes. The Q&A function is to get ° d ONLN dˇˇ ( Z new technical information and ° d ONLN dˇˇ )ù6updates to you quickly, saving the polish for when the ° d ONLN dˇˇ (# Z,information migrates into reference manuals. ° d ONLN dˇˇ *:Q&As are now included with Technical Notes to make access ° d ONLN dˇˇ (;â to technical updates easier for ° d ONLN dˇˇ (G Z/you. If you have comments or suggestions about ° d ONLN dˇˇ )Ú*Q&A content or distribution, please let us ° d ONLN dˇˇ (S Zknow ° d ONLN dˇˇ ) Iby sending an AppleLink to DEVFEEDBACK. Apple Partners may send technical ° d ONLN dˇˇ (_ Z9questions about Q&A content to DEVSUPPORT for resolution. ° d ONLN dˇˇ *NNew Q&As and Q&As revised this month are marked with a bar in the side margin. "n Ü XÜ
° d ONLN dˇˇ *40Macintosh Palette Manager and offscreen graphics
° d ONLN dˇˇ * Written: ° d ONLN dˇˇ )L7/22/91 ° d ONLN dˇˇ (√ ZLast reviewed: ° d ONLN dˇˇ )L8/1/92 ° d ONLN dˇˇ (€ Z8The Macintosh Palette Manager doesn’t work on offscreen ° d ONLN dˇˇ (€âenvironments the way you’d ° d ONLN dˇˇ (Á Zexpect. ° d ONLN dˇˇ )%WUnlike color windows, SetPalette will not change the offscreen’s color table; rather it ° d ONLN dˇˇ (Û Z:just allows you to use PMForeColor and PMBackColor to set ° d ONLN dˇˇ (ÛÄ!the current drawing color in that ° d ONLN dˇˇ (ˇ Z:environment. To change the offscreen’s color table you’ll ° d ONLN dˇˇ (ˇl&need to convert the palette to a color ° d ONLN dˇˇ ( ZZtable and then set the resulting color table to the off screen. Calling Palette2CTab will ° d ONLN dˇˇ ( ˝do the ° d ONLN dˇˇ ( Zconverting for you. ° d ONLN dˇˇ *%To get around having to use palettes ° d ONLN dˇˇ )≠:to define the current drawing color in the off screen, you ° d ONLN dˇˇ (; Z8can always use Index2Color and then RGBForeColor to get ° d ONLN dˇˇ (;x"the color to be set for drawing. A ° d ONLN dˇˇ (G Z%remake of GiMeDaPalette code sample, ° d ONLN dˇˇ )Ω6available on the latest Developer CD Series disc, does ° d ONLN dˇˇ (S Z@offscreen drawing in place of having to continually copy a PICT. ◊ X◊
*ôPalette Manager Q&As (Ï1 ) of 3 ˇ ° ¿Ù%%DSIDICT:_cv
currentdict /bu known {bu}if
userdict /_cv known not{userdict /_cv 30 dict put}if
_cv begin
/bdf{bind def}bind def
currentscreen/cs exch def/ca exch def/cf exch def
/setcmykcolor where{/setcmykcolor get /cvcmyk exch def}{/cvcmyk{1 sub 4 1 roll 3{3 index add neg dup 0 lt{pop 0}if 3 1 roll}repeat setrgbcolor pop}bdf }ifelse
/ss{//cf //ca //cs setscreen}bdf
/stg{ss setgray}bdf
/strgb{ss setrgbcolor}bdf
/stcmyk{ss cvcmyk}bdf
/min1{dup 0 eq{pop 1}if}bdf
end
currentdict /bn known {bn}if
† ø\ ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘
° d ONLN d ) 8ñ *'8RestoreDeviceClut and color flash when application quits
° d ONLN d 9 8 D > * Written: ° d ONLN d B 8 d D à )L8/23/91 ° d ONLN d J D P ] ( l 6Last reviewed: ° d ONLN d Y D d P Ç )L8/1/92 ° d ONLN d ` \ h 8 ( Ñ 6When ° d ONLN d e \ 8 h⁄ ) Umy application, which uses a color palette, quits, there is momentary but distracting ° d ONLN d ª h tC ( ê 6<flash of weird colors in the Finder windows and the desktop ° d ONLN d ˜ hC t⁄ ( êa temporarily appears in a weird ° d ONLN d t Ä fl ( ú 6+color. Is there any way to get around this? ° d ONLN dB Ä å * * ___ ° d ONLN dF ò §2 *:When you quit, RestoreDeviceClut is called to restore the ° d ONLN dÄ ò2 §⁄ ( ¿P"color table and an update event is ° d ONLN d£ § ∞ ¿ ( à 6&called to redraw the screen. It’s the ° d ONLN d… § ¿ ∞⁄ )®:delay between the change in the color table and the update ° d ONLN d ∞ º“ ( ÿ 6Vevent that causes the flash of incorrect colors to be displayed. This, unfortunately, ° d ONLN dZ ∞“ º⁄ ( ÿis ° d ONLN d] º » U ( ‰ 6 unavoidable.
° d ONLN dj ‡ Ô´ *';Restoring Finder desktop colors after using Palette Manager
° d ONLN d¶ Ô ˚ > * Written: ° d ONLN dØ Ô d ˚ à )L8/28/91 ° d ONLN d∑ ˚ ] (# 6Last reviewed: ° d ONLN dΔ ˚ d Ç )L8/1/92 ° d ONLN dÕ æ (; 6XAfter using the Macintosh Palette Manager, how do I restore the Finder’s desktop colors? ° d ONLN d& + * * ___ ° d ONLN d*7 C∂ *UThe Finder desktop’s colors are restored automatically on quitting applications that ° d ONLN d7∂C⁄ (_‘use the ° d ONLN dáC O (k 66Palette Manager. Colors aren’t restored automatically ° d ONLN dΩCO⁄ )˝'when switching from your application to ° d ONLN dÂO [ (w 65another, but if that application needs a certain set ° d ONLN dO [⁄ )Ë-of colors and uses the Palette Manager to get ° d ONLN dH[ gâ (É 6Gthem, then it’ll have them the moment it comes to the front. If you’re ° d ONLN dè[âg⁄ (Éßconcerned about ° d ONLN düg s4 (è 6=applications that don’t use the Palette Manager, you can use ° d ONLN d‹g4s⁄ (èR RestoreDeviceClut(gd:GDHandle), ° d ONLN d¸s ç (õ 6Qpassing the handle to the GDevice of the screen you want to reset, or nil if you ° d ONLN dMsç⁄ (õ´want to reset all ° d ONLN d_ ã ∏ (ß 6 of your devices. Passing nil ° d ONLN d| ∏ã⁄ )†4to RestoreDeviceClut is your best bet, as it is very ° d ONLN d±ã ó? (≥ 6:straightforward, and resets all of your monitors. You may ° d ONLN dÎã?ó⁄ (≥] not wish to do this, however, ° d ONLN d ó £¥ (ø 6Tbecause RestoreDeviceClut is only available on machines with 32-bit color QuickDraw. ° d ONLN d^Ø ªà *ITo reset a screen’s GDevice for machines without 32-bit color QuickDraw, ° d ONLN dßØàª⁄ (◊¶you will need to ° d ONLN d∏ª «] („ 6Gkeep track of the color table.When your application starts up, get the ° d ONLN dˇª]«⁄ („{GDevice’s color table and ° d ONLN d« ” ∂ (Ô 6#save it—you’ll need it later. This ° d ONLN d<« ∂”⁄ )û6value can be found at (**(**GDHandle).gdPMap).pmTable, ° d ONLN ds” fl° (˚ 6Lwhere gdPMap is a PixMapHandle, and pmTable is a CTabHandle which tells you ° d ONLN dø”°fl⁄ (˚ø the absolute ° d ONLN dÃfl Îv ( 6Kcolors for this image. These data structures are found in Inside Macintosh ° d ONLN dflvÎ⁄ (îVolume V, pages 52 ° d ONLN d*Î ˜ B ( 6and 119. ° d ONLN d3 S *@Build your application’s “world” using the Palette Manager, and ° d ONLN dsS⁄ (+qavoid low-level methods of ° d ONLN dé § (7 6Hchanging colors. When your application is about to quit and you want to ° d ONLN d÷§⁄ (7¬ restore the ° d ONLN d‚ '< (C 6Aenvironment to its original state, get the color table you saved ° d ONLN d #<'⁄ (CZ!in the beginning. Convert this to ° d ONLN d E' 3w (O 6Ha palette using CTab2Palette. Then set your window to this palette with ° d ONLN d ç'w3⁄ (OïSetPalette. This will ° d ONLN d £3 ? ([ 6#cause the environment to update to ° d ONLN d Δ3 ?⁄ )≤8the original color table that you initially got from the ° d ONLN d ˇ? K H (g 6 GDevice. ° d ONLN d
? HK⁄ )0WIf the application that is behind your application is Palette Manager friendly, then it ° d ONLN d
`K W` (s 6Bwill restore the environment to its palette. You may also want to ° d ONLN d
¢K`W⁄ (s~do this procedure at the ° d ONLN d
ªW cF ( 6:suspend event, as shown in the DTS sample MacApp program, ° d ONLN d
ıWFc⁄ (d FracApp. One of the problems ° d ONLN d c o A (ã 6 that you ° d ONLN d c Ao⁄ ))Pwon’t be able to solve this way involves multiple monitors. You won’t know which ° d ONLN d lo { ≈ (ó 6%one to update. Only the monitor that ° d ONLN d ëo ≈{⁄ )≠9has the window that you’ve called ActivatePalette on will ° d ONLN d À{ á ; (£ 6update. ° d ONLN d ”ì ü/ *2If your application changes the color environment ° d ONLN d ì/ü⁄ (ªM with the Palette Manager, then ° d ONLN d $ü ´ Ä (« 6RestoreDeviceClut is ° d ONLN d 9ü Ä´⁄ )hEcalled automatically when your application quits. This means that you ◊ 4◊˘
. +Z-Developer Support Center ( -Ê October 1992 / X /
° d ONLN d < ) m ( E Z
shouldn’t ° d ONLN d
m )˛ )1Qhave to worry about restoring the palette if you don’t want to. There is a catch, ° d ONLN d \ ) < 5ä ( Q Z<however (there always is). When you use the SADE version of ° d ONLN d ò )ä 5˛ ( Q®MultiFinder (6.1b9), it ° d ONLN d ∞ 5 < Ac ( ] Z>prevents this from automatically happening. Other versions of ° d ONLN d Ó 5c A˛ ( ]Å MultiFinder don’t have this side ° d ONLN d A < M Z ( i Zeffect.
° d ONLN d e < t *':SetPalette cUpdates, NSetPalette, and window update events
° d ONLN dR t < Ä b * Written: ° d ONLN d[ t à Ä ¨ )L9/26/91 ° d ONLN dc Ä < å Å ( ® ZLast reviewed: ° d ONLN dr Ä à å ¶ )L8/1/92 ° d ONLN dy ò < §fi ( ¿ ZUWhen I pass false in the cUpdates parameter to SetPalette, I still get update events ° d ONLN dŒ òfi §˛ ( ¿¸to that ° d ONLN d÷ § < ∞6 ( à Z2window when I modify its palette. What’s going on? ° d ONLN d ∞ < º N * ___ ° d ONLN d
» < ‘£ *KSetPalette’s cUpdates parameter controls whether color-table changes cause ° d ONLN dX »£ ‘˛ ( ¡that window to get ° d ONLN dk ‘ < ‡d ( ¸ Z<update events only if that window is NOT frontmost. If that ° d ONLN dß ‘d ‡˛ ( ¸Ç window is frontmost, then any ° d ONLN d≈ ‡ < Ïé ( ZKchanges to its palette causes it to get an update event regardless of what ° d ONLN d ‡é Ï˛ (¨the cUpdates parameter ° d ONLN d' Ï < ¯ í ( Zis. When you call ° d ONLN d9 Ï í ¯˛ )VJSetEntryColor and then ActivatePalette for your front-most window, it gets ° d ONLN dÑ ¯ < fl ( Z!an update event because it’s the ° d ONLN d• ¯ fl˛ )£5front-most window even though you passed false in the ° d ONLN d€ < ˘ (, Z&cUpdates parameter. Another important ° d ONLN d ˘˛ )Ω7point is that windows that don’t have palettes also get ° d ONLN d9 < g (8 Z>update events even when another window’s palette is activated. ° d ONLN dx( <4A *6Fortunately, system software version 6.0.2 introduced ° d ONLN dÆ(A4˛ (P_&the NSetPalette routine, which you can ° d ONLN d’4 <@¥ (\ ZLfind documented in the Macintosh Technical Note “Palette Manager Changes in ° d ONLN d!4¥@˛ (\“System 6.0.2,” ° d ONLN d0@ <L P (h Zand ° d ONLN d4@ PL˛ )Ton page 20-20 in the revamped Palette Manager chapter of Inside Macintosh Volume VI. ° d ONLN dâL <Xì (t ZMThis variation of SetPalette gives you a lot more flexibility in controlling ° d ONLN d÷LìX˛ (t±whether your window ° d ONLN dÍX <dY (Ä Z7gets an update event than SetPalette does. If you pass ° d ONLN d!XYd˛ (Äw pmAllUpdates in the nCUpdates ° d ONLN d?d <pk (å Z@parameter, then that window gets an update event when either it ° d ONLN ddkp˛ (åâ or another window’s palette is ° d ONLN dûp <|^ (ò Z;activated. If you pass pmFgUpdates, then it gets an update ° d ONLN dŸp^|˛ (ò|!event when a palette is activated ° d ONLN d˚| <à T (§ Zonly ° d ONLN d | Tà˛ )\if it’s the front-most window (in effect, it only gets an update event if its own palette is ° d ONLN d]à <î’ (∞ ZTactivated). If you pass pmBkUpdates, then it gets an update event when a palette is ° d ONLN d±à’î˛ (∞Û activated ° d ONLN dªî <† ù (º Zonly if it’s not the ° d ONLN d–î ù†˛ )aEfront-most window (in effect, it only gets an update event if another ° d ONLN d† <¨ í (» Zwindow’s palette ° d ONLN d'† í¨˛ )VFis activated). If you pass pmNoUpdates, then that window never gets an ° d ONLN dn¨ <∏— (‘ ZUupdate event from any window’s palette being activated, including that window itself. ◊ X◊
(Ï ZPalette Manager Q&As (Ï3 ) of 3 ˇ f ◊# ˇ ˇˇˇˇ # ◊ † Ç
/ Z Å
0Ià:µú9 " { ˇˇˇˇˇˇˇˇ # † ƒ ° d
ONLN f ˛ † å ° d 1drw2 … -·_ Ä ˇˇˇˇˇˇ è ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˙ ó@ † ò , Times
. R≈ R… x( +]BNew Technical Notes † ô ° d drw2 : °„ † ó ° d 1drw2 eÙ Ä ˇˇˇˇˇˇ P ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä E¿ † ò
Ω ( {íDeveloper Support † ô ° d drw2 : °„ † ó ° d `drw2 - Ô ˇˇˇˇˇˇ K Ô - Z f f Z ° d 1drw2 ¿˙È ˇˇˇˇˇˇ K ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : 0 ° ö ˇÙ Ä † ò
0 Ûe ( UÎ † ô ° d drw2 : °„ † ó ° d 1drw2 ÔÊ˙ ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˝Ä † ò
û? +& ® † ô ° d drw2 : °„ † ó ° d 1drw2  -¯ y ˇˇˇˇˇˇ ° ñ x ° d drw2 : ° d drw2 : $ ° d 4drw2 : ° ö ˇ˚Ä % † ò
ze ( Z \ Macintosh † ô ° d drw2 : °„ † ó † ç ° d drw2 D † É
IR . ° d ONLN d n < Å[ ( õ Z Picture Comments—The Real Deal
° d ONLN d Ä < è r *Imaging ° d ONLN d ' Äv è˛ ( ´îM.IM.PictComments
° d ONLN d 9 õ < ß t ( √ Z Revised by: ° d ONLN d E õ Ñ ß )H
Joseph Maurer ° d ONLN d S õæ ߲ ( √‹ October 1992 ° d ONLN d ` ß < ≥ q ( œ Z Written by: ° d ONLN d l ß Ñ ≥ – )HGinger Jernigan ° d ONLN d | ß± ≥˛ ( œœ
November 1986 ° d ONLN d ä ø < À ‹ ( Á ZChanges since March 1988: ° d ONLN d § ø ‹ À> )†This Note (formerly ° d ONLN d ∏ ø> ÀÚ )b&titled “Optimizing for the LaserWriter ° d ONLN d fi øÚ À˛ )¥— ° d ONLN d fl À < ◊% ( Û Z-PicComments”) describes the picture comments ° d ONLN d À% ◊˛ )È,defined and interpreted by the Apple printer ° d ONLN d9 ◊ < „ ( ˇ Zdrivers. Most ° d ONLN dG ◊ „˛ )CNof the picture comments are specific to PostScript, but we renamed the Note to ° d ONLN dñ „ < Ôû ( ZLemphasize that LaserWriter printers are not necessarily PostScript devices, ° d ONLN d‚ „û Ô˛ ( ºand that QuickDraw ° d ONLN dı Ô < ˚— ( ZLprinter drivers may implement their own picture comment handling. This Note ° d ONLN dA Ô— ˚˛ (Ôhas been ° d ONLN dJ ˚ < (# ZUcompletely rewritten and incorporates all additional insights gained during the last ° d ONLN dü ˚ ˛ (#Ë
few years. ° d ONLN d™ < ` (/ ZWe are ° d ONLN d± `˛ )$Qalso much more determined now to discourage the use of obsolete and problem-laden ° d ONLN d < (; Z-(although still supported) picture comments, ° d ONLN d0 ˛ )Ÿ,and we carefully point out known problems or ° d ONLN d] <+ ƒ (G Z limitations of each comment. V XV
° d ONLN dzD <S è *( Introduction
° d ONLN dá` <l R *The ,
Courier ° d ONLN dã_ Rk É )QDProcs ° d ONLN dí` Él ¿ )1
record (see ° d ONLN dü` ¿l )=Inside Macintosh ° d ONLN dØ`l∑ )R" Volume I, page 197) reflects the ° d ONLN d—`∑l˛ )•foundations of ° d ONLN d‡m <y ì (ï Zthe architecture of ° d ONLN dÙm ìy Á )WQuickDraw. The ° d ONLN dl Áx4 )T commentProc ° d ONLN dm4y˛ )M+ field points to a procedure that processes ° d ONLN d:z <Ü^ (¢ Z;picture comments, as included in a picture by means of the ° d ONLN duy^Ö§ (¢|
PicComment ° d ONLN dz§Ü· )F procedure ( ° d ONLN dãz·Ü˛ )=Inside ° d ONLN díÜ <í m (Æ Z Macintosh ° d ONLN dõÜ mí » )1 Volume I, page ° d ONLN d´Ü »í˛ )[>189). This allows applications to include application-specific ° d ONLN dÍí <û" (∫ Z3additional information in the pictures they create. ° d ONLN d ´ <∑ R *The ° d ONLN d"™ R∂ É )QDProcs ° d ONLN d)´ É∑G )1) record also is the key to understanding ° d ONLN dR´G∑˛ )ƒ#how Macintosh printer drivers work. ° d ONLN dv∏ <ƒ ¬ (‡ ZWhen the application calls ° d ONLN dë∑ ¬√ )Ü
PrOpenPage ° d ONLN dõ∏ƒo )F and draws into the ° d ONLN dØ∏oƒ˛ )g printing grafPort, the printer ° d ONLN dŒ≈ <—Z (Ì Z9driver collects the drawing commands by hooking into the ° d ONLN dƒZ–ã (ÌxQDProcs ° d ONLN d≈ã—ÿ )1 of the printing ° d ONLN d ≈ÿ—˛ )Mport. In ° d ONLN d(“ <fi o (˙ Z particular, ° d ONLN d4“ ofi Î )3 if an application calls the ° d ONLN dP— Λ1 )|
PicComment ° d ONLN dZ“1fi˛ )F* procedure while drawing into the printing ° d ONLN dÖfi <Í ( Z_grafPort, the printer driver gets a chance to capture and process the information contained in ° d ONLN d‰fiͲ (the ° d ONLN dËÍ <ˆ X ( Zkind ° d ONLN dÏÎ X˜ o ) and ° d ONLN dÒÍ oˆ µ )
dataHandle ° d ONLN d˚Î µ˜ Ô )F parameters. ° d ONLN d < Œ (+ Z During the development of the ° d ONLN d& Œ˛ )í@original LaserWriter driver, it became obvious that applications ° d ONLN dg <: (7 Z7should be able to take advantage of certain PostScript ° d ONLN dû:˛ )˛)features that were not accessible through ° d ONLN d» <' ¬ (C Zstandard QuickDraw calls, ° d ONLN d‚ ¬'˛ )Ü@such as rotated text and graphics, dashed lines, fractional line ° d ONLN d#' <3Å (O ZCwidths, and smoothed polygons. Also, certain applications needed a ° d ONLN df'Å3˛ (Oüway to transmit their own ° d ONLN dÄ3 <?ü ([ ZJnative PostScript instructions to the printer. Picture comments seemed to ° d ONLN d 3ü?˛ ([Ωbe the ideal vehicle ° d ONLN dfl? <K — (g Z!for providing these capabilities. ° d ONLN d W <cb *?Unfortunately, there are conflicts with the device-independent ° d ONLN d @Wbc˛ (Ä nature of the Macintosh Printing ° d ONLN d ac <o ‰ (ã Z$Manager architecture. In this Note, ° d ONLN d Öc ‰o˛ )®8we still want to document picture comments as completely ° d ONLN d æo <{ ∂ (ó Zand correctly as possible; ° d ONLN d Ÿo ∂{˛ )zDand we want to tell you how to use the best of their features, while ° d ONLN d
{ <áu (£ ZBmaintaining the important goal of device-independent printing and ° d ONLN d
`{uᲠ(£ì all- purpose PICTs. (This is ° d ONLN d
}á <ì fi (Ø Z#why it has such a painful history!) ◊ X◊
*= Picture Comments—The Real Deal (Ïˇ1 ) of 26 ˇ ° ¿Ù%%DSIDICT:_cv
currentdict /bu known {bu}if
userdict /_cv known not{userdict /_cv 30 dict put}if
_cv begin
/bdf{bind def}bind def
currentscreen/cs exch def/ca exch def/cf exch def
/setcmykcolor where{/setcmykcolor get /cvcmyk exch def}{/cvcmyk{1 sub 4 1 roll 3{3 index add neg dup 0 lt{pop 0}if 3 1 roll}repeat setrgbcolor pop}bdf }ifelse
/ss{//cf //ca //cs setscreen}bdf
/stg{ss setgray}bdf
/strgb{ss setrgbcolor}bdf
/stcmyk{ss cvcmyk}bdf
/min1{dup 0 eq{pop 1}if}bdf
end
currentdict /bn known {bn}if
† ø ñ ◊# ˇ ˇˇˇˇ # ◊
IR , Times
. +6-Macintosh Technical Notes / 4 /˘
° d ONLN d ) Î **First, we give an overview of the picture ° d ONLN d * Î )⁄ )”,comments as currently implemented by Apple’s ° d ONLN d W ) 5 z ( Q 6printer drivers. This ° d ONLN d m ) z 5⁄ )bFleads us immediately to the problem section “Cohabitation of QuickDraw ° d ONLN d ¥ 5 A ˛ ( ] 6.and PostScript,” which also shows how to keep ° d ONLN d ‚ 5 ˛ A⁄ )Ê,the QuickDraw and PostScript graphics states ° d ONLN d A MÃ ( i 6Zsynchronized during printing. Finally, we discuss all the picture comments by subject, in ° d ONLN di AÃ M⁄ ( iÍthe ° d ONLN dm M Y ú ( u 6order suggested by Table 1.
° d ONLN dh ‡ . Î V ( L TextBegin ° d ONLN dr ‡ ç Î ú )_150 ° d ONLN dv ‡ “ Î ◊ )E6 ° d ONLN dx ‡ Î. )0
TTxtPicRec ° d ONLN dÉ ‡J Îî )HBegin text function ° d ONLN dò Ï . ˜ M ( LTextEnd ° d ONLN d† Ï ç ˜ ú )_151 ° d ONLN d§ Ï “ ˜ ◊ )E0 ° d ONLN d¶ Ï ˜ )0NIL ° d ONLN d™ ÏJ ˜ã )HEnd text function ° d ONLN dΩ ¯ . ] ( L StringBegin ° d ONLN d… ¯ ç ú )_152 ° d ONLN dÕ ¯ “ ◊ )E0 ° d ONLN dœ ¯ )0NIL ° d ONLN d” ¯J´ )HBegin string delimitation ° d ONLN dÓ . T (+ L StringEnd ° d ONLN d¯ ç ú )_153 ° d ONLN d¸ “ ◊ )E0 ° d ONLN d˛ )0NIL ° d ONLN dJ¢ )HEnd string delimitation ° d ONLN d . X (7 L
TextCenter ° d ONLN d% ç ú )_154 ° d ONLN d) “ ◊ )E8 ° d ONLN d+- )0
TTxtCenter ° d ONLN d6JØ )H Offset to center of rotation ° d ONLN dT' .2 e (N L
LineLayoutOff ° d ONLN db' ç2 ú )_155 ° d ONLN df' “2 ◊ )E0 ° d ONLN dh'2 )0NIL ° d ONLN dl'J2¡ )H Turn LaserWriter line layout off ° d ONLN dé3 .> d (Z L LineLayoutOn ° d ONLN dõ3 ç> ú )_156 ° d ONLN dü3 “> ◊ )E0 ° d ONLN d°3> )0NIL ° d ONLN d•3J>¿ )H Turn LaserWriter line layout on ° d ONLN d≈? J (f 6# ° d
